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Preface 


This document is being jointly developed by the IEEE and The Open Group and is intended to 
become both IEEE Std. 1003.1-200x and an Open Group Technical Standard, making up the base 
volumes of the Single UNIX Specification, Version 3. 

IEEE Std. 1003.1-200x 

IEEE Std. 1003.1-200x defines the Portable Operating System Interface (POSIX) requirements and 
consists of the following volumes: 

• System Interface Definitions 

• Commands and Utilities (this volume) 

• System Interfaces 

This volume of IEEE Std. 1003.1-200x 

The Commands and Utilities volume of IEEE Std. 1003.1-200x describes the commands and 
utilities offered to application programs on POSIX-conformant systems. Readers are expected to 
be familiar with the System Interface Definitions volume of IEEE Std. 1003.1-200x. 

This volume of IEEE Std. 1003.1-200x is structured as follows: 

• Chapter 1 explains the status of this volume of IEEE Std. 1003.1-200x and its relationship to 
other formal standards. It also describes the defaults used by the utility descriptions in 
Chapter 4. 

• Chapter 2 describes the command language used in POSIX-conformant systems. 

• Chapter 4 consists of reference pages for all utilities available on POSIX-conformant systems. 
Comprehensive references are available in the index. 

Typographical Conventions 

The following typographical conventions are used throughout IEEE Std. 1003.1-200x: 

• Bold font is used in text for options to commands, file names, keywords, type names, data 
structures, and their members. 

• Italic strings are used for emphasis or to identify the first instance of a word requiring 
definition. Italics in text also denote: 

— Command operands, command option-arguments, or variable names; for example, 
substitutable argument prototypes 

— Environment variables, which are also shown in capitals 

— Utility names 

— External variables, such as errno 

— Functions; these are shown as follows: name( ); names without parentheses are C external 
variables, C function family names, utility names, command operands, or command 
option-arguments. 
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Normal font is used for the names of constants and literals. 

The notation <file.h> indicates a header. 

Names surrounded by braces, for example, {ARG_MAX}, represent symbolic limits or 
configuration values which may be declared in appropriate headers by means of the C 
#define construct. 

The notation [EABCD] is used to identify an error value EABCD. 

Syntax, code examples, and user input in interactive examples are shown in fixed width 
font. Brackets shown in this font, [ ], are part of the syntax and do not indicate optional 
items. In syntax the I symbol is used to separate alternatives, and ellipses (...) are used to 
show that additional arguments are optional. 

Bold fixed width font is used to identify brackets that surround optional items in syntax, 
[ ], and to identify system output in interactive examples. 

Variables within syntax statements are shown in italic fixed width font. 

Ranges of values are indicated with parentheses or brackets as follows: 

— ( a,b ) means the range of all values from n to b, including neither a nor b. 

— [a,b] means the range of all values from a to b, including a and b. 

— [a,b) means the range of all values from n to b, including a, but not b. 

— (a,b] means the range of all values from a to b, including b, but not a. 

Shading is used to identify extensions or warnings. 
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This volume of IEEE Std. 1003.1-200x defines a standard source code-level interface to command 
interpretation, or "shell", services and common utility programs for application programs. 
These services and programs are complementary to those specified by the System Interfaces 
volume of IEEE Std. 1003.1-200x. The System Interface Definitions volume of 
IEEE Std. 1003.1-200x defines general terms, concepts, and interfaces used by this volume of 
IEEE Std. 1003.1-200x. When the User Portability Utilities option is included (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance), this volume of 
IEEE Std. 1003.1-200x has additional scope. The list of utilities and features is extended to 
provide a common interactive environment for system users and program developers. 

This volume of IEEE Std. 1003.1-200x has been designed to be used by both application 
programmers and system implementors. When the User Portability Utilities option is included, 
it is also to be used by system users and program developers. However, it is intended to be a 
reference document and not a tutorial on the use of the services, the utilities, or the inter¬ 
relationships between the utilities. 

The emphasis of this volume of IEEE Std. 1003.1-200x without the User Portability Utilities 
option is on the shell and utility functionality required by application programs (including "shell 
scripts"), and not on the direct interactive use of the shell command language or the utilities by 
humans. When the User Portability Utilities option is included, the emphasis is extended to 
support terminal users in a consistent manner across all conforming systems. There are three 
constraining factors that limit this user portability scope: 


23 

24 

25 

26 


1. The users in this context are limited to the group of individuals who are familiar with the 
style of interaction characteristic of historically-derived systems based on one of the UNIX 
operating systems. Typical users would include program developers, engineers, or 
general-purpose time-sharing users. 


27 

28 

29 

30 

31 

32 

33 

34 


2. The environment to be supported is a multi-user time-sharing system supporting 
character-oriented display terminals. Alternatively, it is a collection of single-user systems 
interconnected via local area networks or telephone lines, but with similar user interfaces. 
This volume of IEEE Std. 1003.1-200x does not include support that is tailored for bit¬ 
mapped or graphics display terminals, although it is expected that such terminals could 
emulate the character orientation required by this environment. When facilities require 
cursor addressability from the terminal hardware, this is specifically identified in this 
volume of IEEE Std. 1003.1-200x. 


35 

36 

37 

38 

39 


3. The facilities to be provided are based on the historical models of the following 
documents: the System V Interface Definition, the BSD User Manual, the X/Open Portability 
Guide, and documentation for the KomShell. Emphasis is placed on standardizing existing 
practice for existing users, with changes or additions limited to correcting deficiencies in 
the following areas: 


40 

41 


a. Support for international character sets and other localization requirements, such as 
date formats, collation sequences, and so on 


42 


b. Reconciliation of differences between the historical implementations 
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43 c. Elimination of system or device dependencies 

44 d. Corrections of features that could reduce system or user security/integrity 

45 When the Batch Environment option is included, IEEE Std. 1003d-200x has additional scope. The 

46 list of utilities and features is extended to provide users with a common method to submit work 

47 for deferred processing. This represents support for distributed batch environments, and is 

48 intended to support application and user portability and system interoperability in 

49 heterogeneous environments. Distributed batch environments include traditional batch 

50 processing and other generic queue processes. 

51 This volume of IEEE Std. 1003.1-200x is based upon documentation and the knowledge of 

52 existing programs that assume an interface and architecture similar to that described by the 

53 System Interfaces volume of IEEE Std. 1003.1-200x. Any questions regarding the definition of 

54 terms or the semantics of an underlying concept should be referred to the System Interfaces 

55 volume of IEEE Std. 1003.1-200x. 
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56 1. 

57 

58 


Conformance 

Conformance requirements for IEEE Std. 1003.1-200x are defined in the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance. 
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The following standards contain provisions which, through references in this text, constitute 
provisions of this volume of IEEE Std. 1003.1-200x. At the time of publication, the editions 
indicated were valid. All standards are subject to revision, and parties to agreements based on 
this volume of IEEE Std. 1003.1-200x are encouraged to investigate the possibility of applying 
the most recent editions of the standards listed below. Members of IEC and ISO maintain 
registers of currently valid International Standards. 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

The following list will be updated. 

ISO/IEC 646 

ISO/IEC 646:1991, Information Processing — ISO 7-bit Coded Character Set for Information 
Interchange. 1 

ISO 4217 

ISO 4217:1990, Codes for the Representation of Currencies and Funds. 

ISO/IEC 4873 

ISO/IEC 4873:1991, Information Technology — ISO 8-bit Code for Information Interchange 
— Structure and Rules for Implementation. 

ISO 8601 

ISO 8601:1988, Data Elements and Interchange Formats — Information Interchange — 
Representation of Dates and Times. 

ISO 8859-1 

ISO 8859-1:1987, Information Processing — 8-bit Single-byte Coded Graphic Character Sets 
— Part 1: Latin Alphabet No. 1. 

ISO 8859-2 

ISO 8859-2:1987, Information Processing — 8-bit Single-byte Coded Graphic Character Sets 
— Part 2: Latin Alphabet No. 2. 

ISO/IEC 9899 

ISO/IEC 9899:1990, Programming Languages — C. 

ISO/IEC 9945-1 

ISO/IEC 9945-1:200x, Information Technology — Portable Operating System Interface 
(POSIX) — Part 1: System Application Program Interface (API) [C Language] (identical to 
ANSI/IEEE Std 1003.1-200x). 2 

ANS X3.9-1978 

(Reaffirmed 1989) American National Standard Programming Language FORTRAN. 3 


94 - 

95 1. ISO/IEC documents can be obtained from the ISO office: 1 Rue de Varembe, Case Postale 56, CH-1211, Geneve 20, 

96 Switzerland/Suisse 

97 2. This standard is available from the IEEE Service Center, 445 Eloes Lane, P.O. Box 1331, Piscataway, NJ 08855-1331, U.S.A. Tel: 

98 1 (800) 678-IEEE or +1 (908) 981-1393. 

99 3. ANSI documents can be obtained from the Sales Department, American National Standards Institute, 1430 Broadway, New 

100 York, NY 10018, U.S.A. 
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101 1.4 Changes from Issue 4 

102 Notes to Reviewers 

103 This section with side shading will not appear in the final copy. - Ed. 

104 The change history is subject to revision. The intention is to keep change history from Issue 4, 

105 and in the Issue 5 to Issue 6 change history to note changes from POSIX.2-1992 as well as Issue 5. 

106 The following sections describe changes made to this volume of IEEE Std. 1003.1-200x since 

107 Issue 4. The CHANGE HISTORY section for each utility describes technical changes made to 

108 that utility since Issue 4. Changes made between Issue 2 and Issue 4 are not included. 

109 1.4.1 Changes from Issue 4 to Issue 4, Version 2 

110 The following list summarizes the major changes that were made in this volume of 

111 IEEE Std. 1003.1-200x from Issue 4 to Issue 4, Version 2: 

112 • The X/Open UNIX extension was added, which specifies the common core utilities of 4.3 I 

113 Berkeley Software Distribution (4.3 BSD), the OSF AES, and SVID Issue 3. I 


114 1.4.2 Changes from Issue 4, Version 2 to Issue 5 

115 The following list summarizes the major changes that were made in this volume of 

116 IEEE Std. 1003.1-200x from Issue 4, Version 2 to Issue 5: 


117 

118 
119 


• Large File Summit (LFS) Extensions were added. 

• Some utilities were updated to reflect changes for the POSIX Realtime Extension. 

• Some utilities were updated to reflect changes for the POSIX Threads Extension. 


120 • The LEGACY category of utilities was introduced as a replacement for the TO BE 

121 WITHDRAWN, WITHDRAWN, and Possibly Unsupportable categories. 


122 


• The following utilities were added: 


123 

124 

125 

126 
127 


fuser 

ipcrm 

ipcs 

link 

unlink 


128 1.4.3 Changes from Issue 5 to Issue 6 

129 The following list summarizes the major changes that were made in this volume of 

130 IEEE Std. 1003.1-200x from Issue 5 to Issue 6: 

131 • This volume of IEEE Std. 1003.1-200x is extensively revised so it can be both an IEEE POSIX 

132 Standard and an Open Group Technical Standard. 

133 • this volume of IEEE Std. 1003.1-200x is updated to mandate support of FIPS 151-2. The 

134 following changes were made: 

135 — Support is mandated for the capabilities associated with the following symbolic 

136 constants: 
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137 _POSIX_C HO WN_RESTRIC TED 

138 _POSIXJOB_CONTROL 

139 _POSIX_SAVED_IDS 

140 — In the environment for the login shell, the environment variables LOGNAME and HOME I 

141 shall be defined and have the properties described in the System Interface Definitions I 

142 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

143 • this volume of IEEE Std. 1003.1-200x is updated to align with some features of the Single 

144 UNIX Specification. 

145 • A RATIONALE section is added to each reference page. 

146 • A new chapter on Conformance is added. 

147 • A new chapter on Portability Considerations is added. 


6 


Technical Standard (2000) (Draft February 29, 2000) 



Introduction 


Terminology 


148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161 

162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 

176 

177 

178 

179 

180 
181 
182 

183 

184 

185 

186 

187 

188 

189 

190 

191 

192 


1.5 Terminology 

This section appears in the System Interface Definitions volume of IEEE Std. 1003.1-200x, but is 
repeated here for convenience: 

For the purposes of IEEE Std. 1003.1-200x, the following terminology definitions apply: 

can 

Describes a permissible optional feature or behavior available to the user or application. The 
feature or behavior is mandatory for an implementation that conforms to 
IEEE Std. 1003.1-200x. An application can rely on the existence of the feature or behavior. 

implementation-dependent 

(Same meaning as implementation-defined.) Describes a value or behavior that is not defined 
by IEEE Std. 1003.1-200x but is selected by an implementor. The value or behavior may vary 
among implementations that conform to IEEE Std. 1003.1-200x. An application should not 
rely on the existence of the value or behavior. An application that relies on such a value or 
behavior cannot be assured to be portable across conforming implementations. 

The implementor shall document such a value or behavior so that it can be used correctly 
by an application. 

legacy 

Describes a feature or behavior that is being retained for compatibility with older 
applications, but which has limitations which make it inappropriate for developing portable 
applications. New applications should use alternative means of obtaining equivalent 
functionality. 


may 


Describes a feature or behavior that is optional for an implementation that conforms to 
IEEE Std. 1003.1-200x. An application should not rely on the existence of the feature or 
behavior. An application that relies on such a feature or behavior cannot be assured to be 
portable across conforming implementations. 

To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. 

shall 

For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 
behavior that is mandatory. An application can rely on the existence of the feature or 
behavior. 

For an application or user, describes a behavior that is mandatory. 

should 

For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 
behavior that is recommended but not mandatory. An application should not rely on the 
existence of the feature or behavior. An application that relies on such a feature or behavior 
cannot be assured to be portable across conforming implementations. 

For an application, describes a feature or behavior that is recommended programming 
practice for optimum portability. 

undefined 

Describes the nature of a value or behavior not defined by IEEE Std. 1003.1-200x which 
results from use of an invalid program construct or invalid data input. 

The value or behavior may vary among implementations that conform to 
IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 
value or behavior. An application that relies on any particular value or behavior cannot be 
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193 assured to be portable across conforming implementations. 

194 unspecified 

195 Describes the nature of a value or behavior not specified by IEEE Std. 1003.1-200x which 

196 results from use of a valid program construct or valid data input. 

197 The value or behavior may vary among implementations that conform to 

198 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 

199 value or behavior. An application that relies on any particular value or behavior cannot be 

200 assured to be portable across conforming implementations. 

201 will 

202 Same meaning as shall-, shall is the preferred term. 
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203 1.6 Definitions 

204 Concepts and definitions are defined in the System Interface Definitions volume of 

205 IEEE Std. 1003.1-200X. 


Commands and Utilities, Issue 6 


9 



Relationship to Other Documents 


Introduction 


206 1.7 Relationship to Other Documents 

207 1.7.1 The System Interfaces volume of IEEE Std. 1003.1-200x 

208 This subsection describes some of the features provided by the System Interfaces volume of 

209 IEEE Std. 1003.1-200x that are assumed to be globally available by all systems conforming to this 

210 volume of IEEE Std. 1003.1-200x. This subsection does not attempt to detail all of the features 

211 defined in the System Interfaces volume of IEEE Std. 1003.1-200x that are required by all of the 

212 utilities defined in this volume of IEEE Std. 1003.1-200x; the utility and function descriptions 

213 point out additional functionality required to provide the corresponding specific features 

214 needed by each. 

215 The following subsections describe frequently used concepts. Many of these concepts are 

216 described in the System Interface Definitions volume of IEEE Std. 1003.1-200x. Utility and 

217 function description statements override these defaults when appropriate. 

218 1.7.1.1 Process Attributes 

219 The following process attributes, as described in the System Interfaces volume of 

220 IEEE Std. 1003.1-200x, are assumed to be supported for all processes in this volume of 

221 IEEE Std. 1003.1-200x: 

222 Controlling Terminal 

223 Current Working Directory 

224 Effective Group ID 

225 Effective User ID 

226 File Descriptors 

227 File Mode Creation Mask 

228 Process Group ID 

229 Process ID 

230 A conforming implementation may include additional process attributes. 

231 1.7.1.2 Concurrent Execution of Processes 

232 The following functionality of the fork () function defined in the System Interfaces volume of 

233 IEEE Std. 1003.1-200x shall be available on all systems conforming to this volume of 

234 IEEE Std. 1003.1-200x: 

235 1. Independent processes shall be capable of executing independently without either process 

236 terminating. 

237 2. A process shall be able to create a new process with all of the attributes referenced in 

238 Section 1.7.1.1, determined according to the semantics of a call to the fork() function 

239 defined in the System Interfaces volume of IEEE Std. 1003.1-200x followed by a call in the 

240 child process to one of the exec functions defined in the System Interfaces volume of 

241 IEEE Std. 1003.1-200x. 

242 1.7.1.3 File Access Permissions 

243 The file access control mechanism described by the System Interface Definitions volume of I 

244 IEEE Std. 1003.1-200x, Section 4.1, File Access Permissions applies to all files on an I 

245 implementation conforming to this volume of IEEE Std. 1003.1-200x. 


Real Group ID 
Real User ID 
Root Directory 
Saved Set-Group-ID 
Saved Set-User-ID 
Session Membership 
Supplementary Group IDs 
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246 1.7.1.4 File Read, Write, and Creation 

247 When a file is to be read or written, the file shall be opened with an access mode corresponding 

248 to the operation to be performed. If file access permissions deny access, the requested operation 

249 shall fail. 

250 When a file that does not exist is created, the following features defined in the System Interfaces 

251 volume of IEEE Std. 1003.1-200x shall apply unless the utility or function description states 

252 otherwise: 


253 

254 

255 


1. The user ID of the file is set to the effective user ID of the calling process. 

2. The group ID of the file is set to the effective group ID of the calling process or the group 
ID of the directory in which the file is being created. 


256 


3. If the file is a regular file, the permission bits of the file are set to: 


257 


S_IROTH I SJWOTH I SJRGRP I SJWGRP I SJRUSR I SJWUSR 


258 

259 

260 
261 


(see the description of File Modes in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 13, Headers, <sys/stat.h>) except that the bits specified by 
the file mode creation mask of the process are cleared. If the file is a directory, the 
permission bits are set to: 


262 


S_IRWXU I SJRWXG I SJRWXO 


263 


except that the bits specified by the file mode creation mask of the process are cleared. 


264 4. The st_atime, st_ctime, and stjntime fields of the file shall be updated as specified in the 

265 System Interfaces volume of IEEE Std. 1003.1-200x, Section 2.5, Standard I/O Streams. 


266 5. If the file is a directory, it shall be an empty directory; otherwise, the file shall have length 

267 zero. 


268 

269 

270 


6. If the file is a symbolic link, the effect shall be undefined unless the |POSIX2_SYMLINKS} I 

variable is in effect for the directory in which the symbolic link would be created. I 

7. Unless otherwise specified, the file created shall be a regular file. I 


271 When an attempt is made to create a file that already exists, the action shall depend on the file 

272 type: 


273 

274 

275 


1. For directories and FIFO special files, the attempt shall fail and the utility shall either 
continue with its operation or exit immediately with a non-zero status, depending on the 
description of the utility. 


276 


2. For regular files: 


277 

278 

279 


a. The user ID, group ID, and permission bits of the file shall not be changed. 

b. The file shall be truncated to zero length. 

c. The st_ctime and st_mtime fields shall be marked for update. 


280 


3. For other file types, the effect is implementation-dependent. 


281 When a file is to be appended, the file shall be opened in a manner equivalent to using the 

282 0_APPEND flag, without the 0_TRUNC flag, in the open() function defined in the System 

283 Interfaces volume of IEEE Std. 1003.1-200x. 
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284 1.7.1.5 File Removal 


When a directory that is the root directory or current working directory of any process is 
removed, the effect is implementation-dependent. If file access permissions deny access, the 
requested operation fails. Otherwise, when a file is removed: 

1. Its directory entry is removed from the file system. 

2. The link count of the file is decremented. 

3. If the file is an empty directory (see the System Interface Definitions volume of I 

IEEE Std. 1003.1-200x, Section 3.145, Empty Directory): I 

a. If no process has the directory open, the space occupied by the directory is freed and 
the directory is no longer accessible. 

b. If one or more processes have the directory open, the directory contents are 
preserved until all references to the file have been closed. 

4. If the file is a directory that is not empty, the st_ctime field is marked for update. 

5. If the file is not a directory: 

a. If the link count becomes zero: 

i. If no process has the file open, the space occupied by the file is freed and the 
file is no longer accessible. 

ii. If one or more processes have the file open, the file contents are preserved until 
all references to the file have been closed. 

b. If the link count is not reduced to zero, the st_ctime field is marked for update. 

6. The st_ctime and st_mtime fields of the containing directory are marked for update. 


305 1.7.1.6 File Time Values 


All files shall have the three time values described by the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 4.3, File Times Update. I 


308 1.7.1.7 File Contents 

309 When a reference is made to the contents of a file, pathname, this means the equivalent of all of 

310 the data placed in the space pointed to by buf when performing the read() function calls in the 

311 following operations defined in the System Interfaces volume of IEEE Std. 1003.1-200x: 

312 while (read (fildes, buf, nbytes) > 0) 

313 ; 

314 If the file is indicated by a path name pathname, the file descriptor shall be determined by the 

315 equivalent of the following operation defined in the System Interfaces volume of 

316 IEEE Std. 1003.1-200x: 

317 fildes = open (pathname, 0_RD0NLY); 

318 The value of nbytes in the above sequence is unspecified; if the file is of a type where the data 

319 returned by read() would vary with different values, the value is one that results in the most 

320 data being returned. 

321 If the read( ) function calls would return an error, it is unspecified whether the contents of the file 

322 are considered to include any data from offsets in the file beyond where the error would be 

323 returned. 
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324 1.7.1.8 Path Name Resolution 


325 

326 

327 

328 


The path name resolution algorithm, described by the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 4.5, Path Name Resolution, is used by implementations I 
conforming to this volume of IEEE Std. 1003.1-200x; see also the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.171, File Hierarchy. I 


329 1.7.1.9 Changing the Current Working Directory 


330 

331 

332 

333 

334 


When the current working directory (see the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 3.433, Working Directory) is to be changed, unless the utility or I 

function description states otherwise, the operation shall succeed unless a call to the chdir() 
function defined in the System Interfaces volume of IEEE Std. 1003.1-200x would fail when 
invoked with the new working directory path name as its argument. 


335 1.7.1.10 Establish the Locale 


336 

337 

338 

339 

340 


The functionality of the setlocale() function defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x is assumed to be available on all systems conforming to this volume of 
IEEE Std. 1003.1-200x; that is, utilities that require the capability of establishing an international 
operating environment shall be permitted to set the specified category of the international 
environment. 


341 1.7.1.11 Actions Equivalent to Functions 


342 

343 

344 

345 


Some utility descriptions specify that a utility performs actions equivalent to a function defined 
in the System Interfaces volume of IEEE Std. 1003.1-200x. Such specifications require only that 
the external effects be equivalent, not that any effect within the utility and visible only to the 
utility be equivalent. 
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346 1.8 Portability 

347 Some of the utilities in the Commands and Utilities volume of IEEE Std. 1003.1-200x and 

348 functions in the System Interfaces volume of IEEE Std. 1003.1-200x describe functionality that 

349 might not be fully portable to systems meeting the requirements for POSIX conformance (see the 

350 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance). 

351 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in 

352 the margin identifies the nature of the option, extension, or warning (see Section 1.8.1). For 

353 maximum portability, an application should avoid such functionality. 

354 Unless the primary task of a utility is to produce textual material on its standard output, 

355 application developers should not rely on the format or content of any such material that may be 

356 produced. Where the primary task is to provide such material, but the output format is 

357 incompletely specified, the description is marked with the OF margin code and shading. 

358 Application developers are warned not to expect that the output of such an interface on one 

359 system is any guide to its behavior on another system. 

360 1.8.1 Codes 

361 Codes and their meanings are listed in the System Interface Definitions volume of 

362 IEEE Std. 1003.1-200x, but are repeated here for convenience: 

363 adv Advisory Information 

364 The functionality described is optional. The functionality described is also an extension to the 

365 ISO C standard. 

366 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. 

367 Where additional semantics apply to a function, the material is identified by use of the ADV 

368 margin legend. 

369 aio Asynchronous Input and Output 

370 The functionality described is optional. The functionality described is also an extension to the 

371 ISO C standard. 

372 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. 

373 Where additional semantics apply to a function, the material is identified by use of the AIO 

374 margin legend. 

375 bar Barriers 

376 The functionality described is optional. The functionality described is also an extension to the 

377 ISO C standard. 

378 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. 

379 Where additional semantics apply to a function, the material is identified by use of the BAR 

380 margin legend. 

381 be Batch Environment Services and Utilities 

382 The functionality described is optional. 

383 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. 

384 Where additional semantics apply to a utility, the material is identified by use of the BE margin 

385 legend. 

386 cd C-Language Development Utilities 

387 The functionality described is optional. 

388 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. 

389 Where additional semantics apply to a utility, the material is identified by use of the CD margin 
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390 legend. 

391 cpt Process CPU-Time Clocks 

392 The functionality described is optional. The functionality described is also an extension to the 

393 ISO C standard. 

394 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. 

395 Where additional semantics apply to a function, the material is identified by use of the CPT 

396 margin legend. 

397 cs Clock Selection 

398 The functionality described is optional. The functionality described is also an extension to the 

399 ISO C standard. 

400 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. 

401 Where additional semantics apply to a function, the material is identified by use of the CS 

402 margin legend. 

403 cx Extension to the ISO C standard 

404 The functionality described is an extension to the ISO C standard. Application writers may 

405 confidently make use of an extension as it is supported on all IEEE Std. 1003.1-200x conforming 

406 systems. 

407 fd FORTRAN Development Utilities 

408 The functionality described is optional. 

409 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. 

410 Where additional semantics apply to a utility, the material is identified by use of the FD margin 

411 legend. 

412 fr FORTRAN Runtime Utilities 

413 The functionality described is optional. 

414 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. 

415 Where additional semantics apply to a utility, the material is identified by use of the FR margin 

416 legend. 

417 fsc File Synchronization 

418 The functionality described is optional. The functionality described is also an extension to the 

419 ISO C standard. 

420 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. 

421 Where additional semantics apply to a function, the material is identified by use of the FSC 

422 margin legend. 

423 IP6 IPV6 

424 The functionality described is optional. The functionality described is also an extension to the 

425 ISO C standard. 

426 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. 

427 Where additional semantics apply to a function, the material is identified by use of the IP6 

428 margin legend. 

429 man Mandatory in the Next Draft 

430 This is an interim draft code used to aid reviewers during the development of 

431 IEEE Std. 1003.1-200x. It denotes a feature that was previously an option or extension that is 

432 being brought into the mandatory base functionality. This margin code will be removed from the 

433 final draft. 
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434 mf Memory Mapped Files 

435 The functionality described is optional. The functionality described is also an extension to the 

436 ISO C standard. 

437 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. 

438 Where additional semantics apply to a function, the material is identified by use of the MF 

439 margin legend. 

440 ml Process Memory Locking 

441 The functionality described is optional. The functionality described is also an extension to the 

442 ISO C standard. 

443 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. 

444 Where additional semantics apply to a function, the material is identified by use of the ML 

445 margin legend. 

446 mlr Range Memory Locking 

447 The functionality described is optional. The functionality described is also an extension to the 

448 ISO C standard. 

449 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. 

450 Where additional semantics apply to a function, the material is identified by use of the MLR 

451 margin legend. 

452 mon Monotonic Clock 

453 The functionality described is optional. The functionality described is also an extension to the 

454 ISO C standard. 

455 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. 

456 Where additional semantics apply to a function, the material is identified by use of the MON 

457 margin legend. 

458 mpr Memory Protection 

459 The functionality described is optional. The functionality described is also an extension to the 

460 ISO C standard. 

461 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. 

462 Where additional semantics apply to a function, the material is identified by use of the MPR 

463 margin legend. 

464 msg Message Passing 

465 The functionality described is optional. The functionality described is also an extension to the 

466 ISO C standard. 

467 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. 

468 Where additional semantics apply to a function, the material is identified by use of the MSG 

469 margin legend. 

470 ob Obsolescent 

471 The functionality described may be withdrawn in a future version of this volume of 

472 IEEE Std. 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI 

473 Applications shall not use obsolescent features. 

474 of Output Format Incompletely Specified 

475 The functionality described is an XSI extension. The format of the output produced by the utility 

476 is not fully specified. It is therefore not possible to post-process this output in a consistent 

477 fashion. Typical problems include unknown length of strings and unspecified field delimiters. 
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478 oh Optional Header 

479 In the SYNOPSIS section of some interfaces in the System Interfaces volume of 

480 IEEE Std. 1003.1-200x an included header is marked as in the following example: 

481 OH #include <sys/types.h> 

482 #include <grp.h> 

483 struct group *getgrnam(const char *name); 

484 This indicates that the marked header is not required on XSI-conformant systems. 

485 pi The Behavior Cannot be Guaranteed to be Consistent 

486 The functionality described is an XSI extension. It is not possible to guarantee that the utility 

487 behaves in the same way on all conformant systems. This is the case if it provides functionality 

488 that is implementation-dependent. Options that are used to select alternative forms of 

489 implementation-dependent behavior are not marked, as it is clear from their descriptions that 

490 their use is inherently non-portable. 

491 pio Prioritized Input and Output 

492 The functionality described is optional. The functionality described is also an extension to the 

493 ISO C standard. 

494 Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. 

495 Where additional semantics apply to a function, the material is identified by use of the PIO 

496 margin legend. 

497 ps Process Scheduling 

498 The functionality described is optional. The functionality described is also an extension to the 

499 ISO C standard. 

500 Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. 

501 Where additional semantics apply to a function, the material is identified by use of the PS 

502 margin legend. 

503 rts Realtime Signals Extension 

504 The functionality described is optional. The functionality described is also an extension to the 

505 ISO C standard. 

506 Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. 

507 Where additional semantics apply to a function, the material is identified by use of the RTS 

508 margin legend. 

509 rwl Reader /Writer Locks 

510 The functionality described is optional. The functionality described is also an extension to the 

511 ISO C standard. 

512 Where applicable, functions are marked with the RWL margin legend in the SYNOPSIS section. 

513 Where additional semantics apply to a function, the material is identified by use of the RWL 

514 margin legend. 

515 sd Software Development Utilities 

516 The functionality described is optional. 

517 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. 

518 Where additional semantics apply to a utility, the material is identified by use of the SD margin 

519 legend. 

520 sem Semaphores 

521 The functionality described is optional. The functionality described is also an extension to the 

522 ISO C standard. 
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523 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. 

524 Where additional semantics apply to a function, the material is identified by use of the SEM 

525 margin legend. 

526 shm Shared Memory Objects 

527 The functionality described is optional. The functionality described is also an extension to the 

528 ISO C standard. 

529 Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. 

530 Where additional semantics apply to a function, the material is identified by use of the SHM 

531 margin legend. 

532 sio Synchronized Input and Output 

533 The functionality described is optional. The functionality described is also an extension to the 

534 ISO C standard. 

535 Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. 

536 Where additional semantics apply to a function, the material is identified by use of the SIO 

537 margin legend. 

538 spi Spin Locks 

539 The functionality described is optional. The functionality described is also an extension to the 

540 ISO C standard. 

541 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. 

542 Where additional semantics apply to a function, the material is identified by use of the SPI 

543 margin legend. 

544 spn Spawn 

545 The functionality described is optional. The functionality described is also an extension to the 

546 ISO C standard. 

547 Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. 

548 Where additional semantics apply to a function, the material is identified by use of the SPN 

549 margin legend. 

550 ss Process Sporadic Server 

551 The functionality described is optional. The functionality described is also an extension to the 

552 ISO C standard. 

553 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. 

554 Where additional semantics apply to a function, the material is identified by use of the SS 

555 margin legend. 

556 tct Thread CPU-Time Clocks 

557 The functionality described is optional. The functionality described is also an extension to the 

558 ISO C standard. 

559 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. 

560 Where additional semantics apply to a function, the material is identified by use of the TCT 

561 margin legend. 

562 thr Threads 

563 The functionality described is optional. The functionality described is also an extension to the 

564 ISO C standard. 

565 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. 

566 Where additional semantics apply to a function, the material is identified by use of the THR 

567 margin legend. 
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568 

TMO 

Timeouts 

569 


The functionality described is optional. 

570 


ISO C standard. 

571 


Where applicable, functions are marked 

572 


Where additional semantics apply to a 

573 


margin legend. 

574 

TMR 

Timers 

575 


The functionality described is optional. 

576 


ISO C standard. 

577 


Where applicable, functions are marked 

578 


Where additional semantics apply to a 

579 


margin legend. 

580 

TPI 

Threads Priority Inheritance 

581 


The functionality described is optional. 

582 


ISO C standard. 

583 


Where applicable, functions are marked 

584 


Where additional semantics apply to a 

585 


margin legend. 

586 

TPP 

Thread Priority Protection 

587 


The functionality described is optional. 

588 


ISO C standard. 

589 


Where applicable, functions are marked 

590 


Where additional semantics apply to a 

591 


margin legend. 

592 

TPS 

Thread Execution Scheduling 

593 


The functionality described is optional. 

594 


ISO C standard. 

595 


Where applicable, functions are marked 

596 


Where additional semantics apply to a 

597 


margin legend. 

598 

TSA 

Thread Stack Address Attribute 

599 


The functionality described is optional. 

600 


ISO C standard. 

601 


Where applicable, functions are marked 

602 


Where additional semantics apply to a 

603 


margin legend. 

604 

TSF 

Thread-Safe Functions 

605 


The functionality described is optional. 

606 


ISO C standard. 

607 


Where applicable, functions are marked 

608 


Where additional semantics apply to a 

609 


margin legend. 

610 

TSH 

Thread Process-Shared Synchronization 

611 


The functionality described is optional. 

612 


ISO C standard. 


The functionality described is also an extension to the 

with the TMO margin legend in the SYNOPSIS section, 
function, the material is identified by use of the TMO 

The functionality described is also an extension to the 

with the TMR margin legend in the SYNOPSIS section, 
function, the material is identified by use of the TMR 

The functionality described is also an extension to the 

with the TPI margin legend in the SYNOPSIS section, 
function, the material is identified by use of the TPI 

The functionality described is also an extension to the 

with the TPP margin legend in the SYNOPSIS section, 
function, the material is identified by use of the TPP 

The functionality described is also an extension to the 

with the TPS margin legend for the SYNOPSIS section, 
function, the material is identified by use of the TPS 

The functionality described is also an extension to the 

with the TPS margin legend for the SYNOPSIS section, 
function, the material is identified by use of the TSA 

The functionality described is also an extension to the 

with the TSF margin legend in the SYNOPSIS section, 
function, the material is identified by use of the TSF 

The functionality described is also an extension to the 
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613 Where applicable, functions are marked with the TSH margin legend in the SYNOPSIS section. 

614 Where additional semantics apply to a function, the material is identified by use of the TSH 

615 margin legend. 

616 tsp Thread Sporadic Server 

617 The functionality described is optional. The functionality described is also an extension to the 

618 ISO C standard. 

619 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. 

620 Where additional semantics apply to a function, the material is identified by use of the TSP 

621 margin legend. 

622 tss Thread Stack Address Size 

623 The functionality described is optional. The functionality described is also an extension to the 

624 ISO C standard. 

625 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. 

626 Where additional semantics apply to a function, the material is identified by use of the TSS 

627 margin legend. 

628 tym Typed Memory Objects 

629 The functionality described is optional. The functionality described is also an extension to the 

630 ISO C standard. 

631 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. 

632 Where additional semantics apply to a function, the material is identified by use of the TYM 

633 margin legend. 

634 un Possibly Unsupportable Feature 

635 The functionality described is an XSI extension. It need not be possible to implement the 

636 required functionality (as defined) on all conformant systems and the functionality need not be 

637 present. This may, for example, be the case where the conformant system is hosted and the 

638 underlying system provides the service in an alternative way. 

639 up User Portability Utilities 

640 The functionality described is optional. 

641 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. 

642 Where additional semantics apply to a utility, the material is identified by use of the UP margin 

643 legend. 

644 xsi Extension 

645 The functionality described is an XSI extension. Functionality marked XSI is also an extension to 

646 the ISO C standard. Application writers may confidently make use of an extension on all 

647 systems supporting the X/Open System Interfaces Extension. 

648 If an entire SYNOPSIS section is shaded and marked with one XSI, all the functionality described 

649 in that reference page is an extension. See the System Interface Definitions volume of 

650 IEEE Std. 1003.1-200x, Section 3.436, XSI. 

651 xsr XSI STREAMS 

652 The functionality described is optional. The functionality described is also an extension to the 

653 ISO C standard. 

654 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. 

655 Where additional semantics apply to a function, the material is identified by use of the XSR 

656 margin legend. 
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657 1.9 Utility Limits 

658 This section lists magnitude limitations imposed by a specific implementation. The braces 

659 notation, {LIMIT}, is used in this volume of IEEE Std. 1003.1-200x to indicate these values, but 

660 the braces are not part of the name. 


661 Table 1-1 Utility Limit Minimum Values 


662 

Name 

Description 

Value 

663 

{POSIX2_BC_B ASE_M AX} 

The maximum obase value allowed by the be 

99 

664 


utility. 


665 

{POSIX2_BC_DIM_M AX} 

The maximum number of elements permitted in 

2048 

666 


an array by the be utility. 


667 

{POSIX2_BC_SC ALE_M AX} 

The maximum scale value allowed by the be 

99 

668 


utility. 


669 

{POSIX2_BC_STRING_MAX} 

The maximum length of a string constant 

1000 

670 


accepted by the be utility. 


671 

{POSIX2_COLL_WEIGHTS_MAX} 

The maximum number of weights that can be 

2 

672 


assigned to an entry of the LC_COLLATE order 


673 


keyword in the locale definition file; see the 


674 


border_start keyword in the System Interface 


675 


Definitions volume of IEEE Std. 1003.1-200x, 


676 


Section 7.3.2, LC_COLLATE. 


677 

{POSIX2_EXPR_NEST_M AX} 

The maximum number of expressions that can 

32 

678 


be nested within parentheses by the expr utility. 


679 

{POSIX2_LINE_M AX} 

Unless otherwise noted, the maximum length, in 

2048 

680 


bytes, of the input line of a utility (either 


681 


standard input or another file), when the utility 


682 


is described as processing text files. The length 


683 


includes room for the trailing newline. 


684 

{POSIX2_RE_DUP_M AX} 

The maximum number of repeated occurrences 

255 

685 


of a BRE permitted when using the interval 


686 


notation \{m,n \}; see the System Interface 


687 


Definitions volume of IEEE Std. 1003.1-200x, 


688 


Section 9.3.6, BREs Matching Multiple 


689 


Characters. 


690 

{POSIX2_VERSION} 

This value indicates the version of the utilities in 

199209 

691 


this volume of IEEE Std. 1003.1-200x that are 


692 


provided by the implementation. It changes 


693 


with each published version. 



694 The values specified in Table 1-1 represent the lowest values conforming implementations shall 

695 provide and, consequently, the largest values on which an application can rely without further 

696 enquiries, as described below. These values shall be accessible to applications via the getconf 

697 utility (see getconf on page 517) and through the sysconf() function defined in the System 

698 Interfaces volume of IEEE Std. 1003.1-200x. The literal names shown in Table 1-1 apply only to 

699 the getconf utility; the high-level language binding describes the exact form of each name to be 

700 used by the interfaces in that binding. 

701 Implementations may provide more liberal, or less restrictive, values than shown in Table 1-1. 

702 These possibly more liberal values are accessible using the symbols in Table 1-2 on page 22. 
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703 The sysconf {) function defined in the System Interfaces volume of IEEE Std. 1003.1-200x or the 

704 getconf utility return the value of each symbol on each specific implementation. The value so 

705 retrieved is the largest, or most liberal, value that is available throughout the session lifetime, as 

706 determined at session creation. The literal names shown in the table apply only to the getconf 

707 utility; the high-level language binding describes the exact form of each name to be used by the 

708 interfaces in that binding. 

709 All numeric limits defined by the System Interfaces volume of IEEE Std. 1003.1-200x, such as 

710 {PATH_MAX}, also apply to this volume of IEEE Std. 1003.1-200x. All the utilities defined by this 

711 volume of IEEE Std. 1003.1-200x are implicitly limited by these values, unless otherwise noted in 

712 the utility descriptions. 

713 It is not guaranteed that the application can in fact push a value to the specified limit of an 

714 implementation in any given case, or at all, as a lack of virtual memory or other resources may 

715 prevent this. The limit value indicates only that the implementation does not specifically impose 

716 any arbitrary, more restrictive limit. 

717 Table 1-2 Symbolic Utility Limits 

718 


719 

Name 

Description 

Minimum Value 

720 

|BC_BASE_MAX} 

The maximum obase value 

|POSIX2_BC_BASE_MAX} 

721 


allowed by the be utility. 


722 

j BC_DIM_MAX) 

The maximum number of 

j POSIX2_BC_DIM_M AX} 

723 


elements permitted in an 


724 


array by the be utility. 


725 

|BC_SCALE_MAX} 

The maximum scale value 

|POSIX2_BC_SC ALE_M AX} 

726 


allowed by the be utility. 


727 

|BC_STRING_MAX} 

The maximum length of a 

j POSIX2_BC_STRING_MAX [ 

728 


string constant accepted by 


729 


the be utility. 


730 

|COLL_WEIGHTS_MAX} 

The maximum number of 

j POSIX2_COLL_WEIGHTS_MAX) 

731 


weights that can be 


732 


assigned to an entry of the 


733 


LC_COLLATE order 


734 


keyword in the locale 


735 


definition file; see the 


736 


order_start keyword in the 


737 


System Interface Definitions 


738 


volume of 


739 


IEEE Std. 1003.1-200x, 


740 


Section 7.3.2, LC_COLLATE. 


741 

{EXPR_NEST_MAX} 

The maximum number of 

j POSIX2_EXPR_NEST_M AX) 

742 


expressions that can be 


743 


nested within parentheses 


744 


by the expr utility. 


745 

{LINE_MAX| 

Unless otherwise noted, the 

{POSIX2_LINE_M AX} 

746 


maximum length, in bytes. 


747 


of the input line of a utility 


748 


(either standard input or 


749 


another file), when the 


750 
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751 


752 

Name 

Description 

Minimum Value 

753 


utility is described as 


754 


processing text files. The 


755 


length includes room for the 


756 


trailing newline. 


757 

j RE_DUP_M AX} 

The maximum number of 

j POSIX2_RE_DUP_M AX} 

758 


repeated occurrences of a 


759 


BRE permitted when using 


760 


the interval notation 


761 


\{m,n\); see the System 


762 


Interface Definitions 


763 


volume of 


764 


IEEE Std. 1003.1-200x, 


765 


Section 9.3.6, BREs 


766 


Matching Multiple 


767 


Characters. 



768 The following value may be a constant within an implementation or may vary from one path 

769 name to another. 

770 {POSIX2_S YMLINKS} 

771 When referring to a directory, the system supports the creation of symbolic links within that 

772 directory; for non-directory files, the meaning of {POSIX2_S YMLINKS) is undefined. 

773 Rationale 

774 The |POSIX2_SYMLINKS} variable indicates that the underlying operating system supports the 

775 creation of symbolic links in specific directories. Many of the utilities defined in the 

776 IEEE Std. 1003.1-200x that deal with symbolic links do not depend on this value. For example, a 

777 utility that follows symbolic links (or does not, as the case may be) will only be affected by a 

778 symbolic link if it encounters one. Presumably, a file system that does not support symbolic links 

779 will not contain any. This variable does affect such utilities as In -s and pax that attempt to create 

780 symbolic links. 

781 {POSIX2_SYMLINKS} was developed even though there is no comparable configuration value 

782 in the IEEE P1003.1a draft standard. 

783 Notes to Reviewers 

784 This section with side shading will not appear in the final copy. - Ed. 

785 Do we want to add POSIX2_SYMLINKS to <u n i s td. h >/si/sco nf( ) and remove the last sentence? 
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786 1.10 Grammar Conventions 

787 Portions of this volume of IEEE Std. 1003.1-200x are expressed in terms of a special grammar 

788 notation. It is used to portray the complex syntax of certain program input. The grammar is 

789 based on the syntax used by the yacc utility. However, it does not represent fully functional yacc 

790 input, suitable for program use; the lexical processing and all semantic requirements are 

791 described only in textual form. The grammar is not based on source used in any traditional 

792 implementation and has not been tested with the semantic code that would normally be 

793 required to accompany it. Furthermore, there is no implication that the partial yacc code 

794 presented represents the most efficient, or only, means of supporting the complex syntax within 

795 the utility. Implementations may use other programming languages or algorithms, as long as the 

796 syntax supported is the same as that represented by the grammar. 

797 The following typographical conventions are used in the grammar; they have no significance 

798 except to aid in reading. 

799 • The identifiers for the reserved words of the language are shown with a leading capital letter. 

800 (These are terminals in the grammar; for example. While, Case.) 

801 • The identifiers for terminals in the grammar are all named with uppercase letters and 

802 underscores; for example, NEWLINE, ASSIGN_OP, NAME. 

803 • The identifiers for non-terminals are all lowercase. 
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804 1.11 Utility Description Defaults 

805 This section describes all of the subsections used within the utility descriptions, including: 

806 • Intended usage of the section 

807 • Global defaults that affect all the standard utilities 


808 • The meanings of notations used in this volume of IEEE Std. 1003.1-200x that are specific to 

809 individual utility sections 

810 Integer variables and constants, including the values of operands and option-arguments, used 

811 by the utilities listed in this volume of IEEE Std. 1003.1-200x shall be implemented as equivalent 

812 to the ISO C standard signed long data type. Conversion between types shall be as described in 

813 the ISO C standard. The evaluation of arithmetic expressions shall be equivalent to that 

814 described in Section 6.3 of the ISO C standard. 


815 NAME 

816 This section gives the name or names of the utility and briefly states its purpose. 

817 SYNOPSIS 

818 The SYNOPSIS section summarizes the syntax of the calling sequence for the utility, 

819 including options, option-arguments, and operands. Standards for utility naming are 

820 described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 

821 12.2, Utility Syntax Guidelines; for describing the utility's arguments in the System 

822 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 12.1, Utility Argument 

823 Syntax. 


824 DESCRIPTION 

825 The DESCRIPTION section describes the actions of the utility. If the utility has a very 

826 complex set of subcommands or its own procedural language, an EXTENDED 

827 DESCRIPTION section is also provided. Most explanations of optional functionality are 

828 omitted here, as they are usually explained in the OPTIONS section. 

829 Some utilities in this volume of IEEE Std. 1003.1-200x are described in terms of 

830 functionality equivalent to the System Interfaces volume of IEEE Std. 1003.1-200x. 

831 When specific functions are cited, the underlying operating system provides equivalent 

832 functionality and all side effects associated with successful execution of the function. 

833 The treatment of errors and intermediate results from the individual functions cited is 

834 generally not specified by this volume of IEEE Std. 1003.1-200x. See the utility's EXIT 

835 STATUS and CONSEQUENCES OF ERRORS sections for all actions associated with 

836 errors encountered by the utility. 


837 OPTIONS 

838 The OPTIONS section describes the utility options and option-arguments, and how 

839 they modify the actions of the utility. Standard utilities that have options either fully I 

840 comply with the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section I 

841 12.2, Utility Syntax Guidelines or describe all deviations. Apparent disagreements I 

842 between functionality descriptions in the OPTIONS and DESCRIPTION (or 

843 EXTENDED DESCRIPTION) sections are always resolved in favor of the OPTIONS 

844 section. 


845 Each OPTIONS section that uses the phrase "The ... utility supports the Utility Syntax 

846 Guidelines ..." refers only to the use of the utility as specified by this volume of 

847 IEEE Std. 1003.1-200x; implementation extensions should also conform to the 

848 guidelines, but may allow exceptions for historical practice. 
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849 Unless otherwise stated in the utility description, when given an option unrecognized 

850 by the implementation, or when a required option-argument is not provided, standard 

851 utilities issue a diagnostic message to standard error and exit with a non-zero exit 

852 status. 


853 xsi All utilities in this volume of IEEE Std. 1003.1-200x are capable of processing arguments 

854 using 8-bit transparency. 

855 Default Behavior: When this section is listed as "None.", it means that the 

856 implementation need not support any options. Standard utilities that do not accept 

857 options, but that do accept operands, recognize "—" as a first argument to be 

858 discarded. 


859 The requirement for recognizing "—" is because portable applications need a way to 

860 shield their operands from any arbitrary options that the implementation may provide 

861 as an extension. For example, if the standard utility foo is listed as taking no options, 

862 and the application needed to give it a path name with a leading hyphen, it could safely 

863 do it as: 


864 foo — —myfile 

865 and avoid any problems with -m used as an extension. 

866 OPERANDS 

867 The OPERANDS section describes the utility operands, and how they affect the actions 

868 of the utility. Apparent disagreements between functionality descriptions in the 

869 OPERANDS and DESCRIPTION (or EXTENDED DESCRIPTION) sections are always 

870 resolved in favor of the OPERANDS section. 


871 If an operand naming a file can be specified as ' - ', which means to use the standard 

872 input instead of a named file, this is explicitly stated in this section. Unless otherwise 

873 stated, the use of multiple instances of to mean standard input in a single 

874 command produces unspecified results. 

875 Unless otherwise stated, the standard utilities that accept operands process those 

876 operands in the order specified in the command line. 

877 Default Behavior: When this section is listed as "None.", it means that the 

878 implementation need not support any operands. 


879 

880 
881 
882 

883 

884 

885 

886 


887 

888 
889 


STDIN 

The STDIN section describes the standard input of the utility. This section is frequently 
merely a reference to the following section, as many utilities treat standard input and 
input files in the same manner. Unless otherwise stated, all restrictions described in the 
INPUT FILES section apply to this section as well. 

Use of a terminal for standard input can cause any of the standard utilities that read 
standard input to stop when used in the background. For this reason, applications 
should not use interactive features in scripts to be placed in the background. 

The specified standard input format of the standard utilities does not depend on the 
existence or value of the environment variables defined in this volume of 
IEEE Std. 1003.1-200x, except as provided by this volume of IEEE Std. 1003.1-200x. 


890 

891 

892 


Default Behavior: When this section is listed as "Not used.", it means that the 
standard input is not read when the utility is used as described by this volume of 


IEEE Std. 1003.1-200x. 
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893 

894 

895 

896 

897 

898 


INPUT FILES 

The INPUT FILES section describes the files, other than the standard input, used as 
input by the utility. It includes files named as operands and option-arguments as well 
as other files that are referred to, such as start-up and initialization files, databases, and I 
so on. Commonly-used files are generally described in one place and cross-referenced I 
by other utilities. 


899 xsi All utilities in this volume of IEEE Std. 1003.1-200x are capable of processing input files 

900 using 8-bit transparency. 


901 When a standard utility reads a seekable input file and terminates without an error 

902 before it reaches end-of-file, the utility ensures that the file offset in the open file 

903 description is properly positioned just past the last byte processed by the utility. For 

904 files that are not seekable, the state of the file offset in the open file description for that 

905 file is unspecified. A portable application cannot assume that the following three 

906 commands are equivalent: 


907 tail — n +2 file 

908 (sed —n lq; cat) < file 

909 cat file | (sed —n lq; cat) 


910 The second command is equivalent to the first only when the file is seekable. The third 

911 command leaves the file offset in the open file description in an unspecified state. Other 

912 utilities, such as head, read, and sh, have similar properties. 


913 

914 

915 

916 

917 

918 

919 

920 

921 

922 

923 


Some of the standard utilities, such as filters, process input files a line or a block at a 
time and have no restrictions on the maximum input file size. Some utilities may have 
size limitations that are not as obvious as file space or memory limitations. Such 
limitations should reflect resource limitations of some sort, not arbitrary limits set by 
implementors. Implementations document those utilities that are limited by constraints 
other than file system space, available memory, and other limits specifically cited by 
this volume of IEEE Std. 1003.1-200x, and identify what the constraint is and indicate a 
way of estimating when the constraint would be reached. Similarly, some utilities 
descend the directory tree (recursively). Implementations also document any limits that 
they may have in descending the directory tree that are beyond limits cited by this 
volume of IEEE Std. 1003.1-200x. 


924 When an input file is described as a text file, the utility produces undefined results if 

925 given input that is not from a text file, unless otherwise stated. Some utilities (for 

926 example, make, read, sh) allow for continued input lines using an escaped <newline> 

927 convention; unless otherwise stated, the utility need not be able to accumulate more 

928 than |LINE_MAX} bytes from a set of multiple, continued input lines. Thus, for a 

929 portable application the total of all the continued lines in a set cannot exceed 

930 |LINE_MAX}. If a utility using the escaped <newline> convention detects an end-of- 

931 file condition immediately after an escaped <newline>, the results are unspecified. 


932 Record formats are described in a notation similar to that used by the C-language 

933 function, print/{). See the System Interface Definitions volume of I 

934 IEEE Std. 1003.1-200x, Chapter 5, File Format Notation for a description of this notation. I 

935 The format description is intended to be sufficiently rigorous to allow other I 

936 applications to generate these input files. However, since <blank> characters can 

937 legitimately be included in some of the fields described by the standard utilities, 

938 particularly in locales other than the POSIX locale, this intent is not always realized. 


939 Default Behavior: When this section is listed as "None.", it means that no input files 

940 are required to be supplied when the utility is used as described by this volume of 
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941 


IEEE Std. 1003.1-200x. 


942 

943 

944 

945 

946 

947 

948 

949 

950 

951 

952 

953 

954 

955 

956 

957 

958 

959 

960 

961 

962 

963 

964 

965 

966 

967 

968 

969 

970 

971 

972 

973 

974 

975 

976 

977 

978 

979 

980 

981 

982 

983 

984 


ENVIRONMENT VARIABLES 

The ENVIRONMENT VARIABLES section lists what variables affect the utility's 
execution. 


described in this volume of 
utility is described in the 


The entire manner in which environment variables 
IEEE Std. 1003.1-200x affect the behavior of each 
ENVIRONMENT VARIABLES section for that utility, in conjunction with the global 
xsi effects of the LANG, LC_ALL, and NLSPATH environment variables described in the I 

System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment I 
Variables. The existence or value of environment variables described in this volume of I 
IEEE Std. 1003.1-200x do not otherwise affect the specified behavior of the standard 
utilities. Any effects of the existence or value of environment variables not described by 
this volume of IEEE Std. 1003.1-200x upon the standard utilities are unspecified. 

For those standard utilities that use environment variables as a means for selecting a 
utility to execute (such as CC in make), the string provided to the utility is subjected to 
the path search described for PATH in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

xsi All utilities in this volume of IEEE Std. 1003.1-200x are capable of processing 

environment variable names and values using 8-bit transparency. 

Default Behavior: When this section is listed as "None.", it means that the behavior of 
the utility is not directly affected by environment variables described by this volume of 
IEEE Std. 1003.1-200x when the utility is used as described by this volume of 
IEEE Std. 1003.1-200x. 

ASYNCHRONOUS EVENTS 

The ASYNCHRONOUS EVENTS section lists how the utility reacts to such events as 
signals and what signals are caught. 

Default Behavior: When this section is listed as "Default.", or it refers to "the standard 
action for all other signals; see Section 1.11 on page 25" it means that the action taken 
as a result of the signal is one of the following: 

1. The action is that inherited from the parent according to the rules of inheritance 
of signal actions defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 

2. When no action has been taken to change the default, the default action is that 
specified by the System Interfaces volume of IEEE Std. 1003.1-200x. 

3. The result of the utility's execution is as if default actions had been taken. 

A utility is permitted to catch a signal, perform some additional processing (such as 
deleting temporary files), restore the default signal action (or action inherited from the 
parent process), and resignal itself. 


STDOUT 


The STDOUT section describes the standard output of the utility. This section is 
frequently merely a reference to the following section, OUTPUT FILES, because many 
utilities treat standard output and output files in the same manner. 

Use of a terminal for standard output may cause any of the standard utilities that write 
standard output to stop when used in the background. For this reason, applications 
should not use interactive features in scripts to be placed in the background. 
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985 Record formats are described in a notation similar to that used by the C-language 

986 function, printf(). See the System Interface Definitions volume of I 

987 IEEE Std. 1003.1-200x, Chapter 5, File Format Notation for a description of this notation. I 

988 The specified standard output of the standard utilities does not depend on the existence 

989 or value of the environment variables defined in this volume of IEEE Std. 1003.1-200x, 

990 except as provided by this volume of IEEE Std. 1003.1-200x. 

991 Some of the standard utilities describe their output using the verb display, defined in I 

992 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.135, I 

993 Display. Output described in the STDOUT sections of such utilities may be produced I 

994 using means other than standard output. When standard output is directed to a 

995 terminal, the output described is written directly to the terminal. Otherwise, the results 

996 are undefined. 


997 

998 

999 


Default Behavior: When this section is listed as "Not used.", it means that the 
standard output is not written when the utility is used as described by this volume of 


IEEE Std. 1003.1-200x. 


1000 STDERR 

1001 The STDERR section describes the standard error output of the utility. Only those 

1002 messages that are purposely sent by the utility are described. 

1003 Use of a terminal for standard error may cause any of the standard utilities that write 

1004 standard error output to stop when used in the background. For this reason, 

1005 applications should not use interactive features in scripts to be placed in the 

1006 background. 


1007 The format of diagnostic messages for most utilities is unspecified, but the language 

1008 and cultural conventions of diagnostic and informative messages whose format is 

1009 unspecified by this volume of IEEE Std. 1003.1-200x should be affected by the setting of 

1010 xsi LC_MESSAGES andNLSPATH. 


1011 

1012 

1013 


The specified standard error output of standard utilities does not depend on the 
existence or value of the environment variables defined in this volume of 
IEEE Std. 1003.1-200x, except as provided by this volume of IEEE Std. 1003.1-200x. 


1014 

1015 

1016 
1017 


Default Behavior: When this section is listed as "Used only for diagnostic messages.", 
it means that, unless otherwise stated, the diagnostic messages are sent to the standard 
error only when the exit status is non-zero and the utility is used as described by this 
volume of IEEE Std. 1003.1-200x. 


1018 When this section is listed as "Not used.", it means that the standard error is not used 

1019 when the utility is used as described in this volume of IEEE Std. 1003.1-200x. 

1020 This section does not describe error messages that refer to incorrect operation of the 

1021 utility. Consider a utility that processes program source code as its input. This section 

1022 is used to describe messages produced by a correctly operating utility that encounters 

1023 an error in the program source code on which it is processing. However, a message 

1024 indicating that the utility had insufficient memory in which to operate would not be 

1025 described. 


1026 Some utilities have traditionally produced warning messages without returning a non- 

1027 zero exit status; these are specifically noted in their sections. Other utilities are expected 

1028 to remain absolutely quiet on the standard error if they want to return zero, unless the 

1029 implementation provides some sort of extension to increase the verbosity or debugging 

1030 level. 
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1031 OUTPUT FILES 

1032 The OUTPUT FILES section describes the files created or modified by the utility. 

1033 Temporary or system files that are created for internal usage by this utility or other 

1034 parts of the implementation (for example, spool, log, and audit files) are not described 

1035 in this, or any, section. The utilities creating such files and the names of such files are 

1036 unspecified. If applications are written to use temporary or intermediate files, they 

1037 should use the TMPDIR environment variable, if it is set and represents an accessible 

1038 directory, to select the location of temporary files. 

1039 Temporary files used by the standard utilities are named so that different utilities or 

1040 multiple instances of the same utility can operate simultaneously without regard to 

1041 their working directories, or any other process characteristic other than process ID. 

1042 There are two exceptions to this rule: 


1043 

1044 


1. Resources for temporary files other than the name space (for example, disk space, 
available directory entries, or number of processes allowed) are not guaranteed. 


1045 

1046 

1047 

1048 


2. Certain standard utilities generate output files that are intended as input for other 
utilities (for example, lex generates lex.yy.c), and these cannot have unique 
names. These cases are explicitly identified in the descriptions of the respective 
utilities. 


1049 Any temporary file created by the implementation is removed by the implementation 

1050 upon a utility's successful exit, exit because of errors, or before termination by any of 

1051 the SIGHUP, SIGINT, or SIGTERM signals, unless specified otherwise by the utility 

1052 description. 

1053 Receipt of the SIGQUIT signal should generally cause termination (unless in some 

1054 debugging mode) that would bypass any attempted recovery actions. 

1055 Record formats are described in a notation similar to that used by the C-language 

1056 function, printf (); see the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

1057 Chapter 5, File Format Notation for a description of this notation. I 

1058 Default Behavior: When this section is listed as "None.", it means that no files are 

1059 created or modified as a consequence of direct action on the part of the utility when the 

1060 utility is used as described by this volume of IEEE Std. 1003.1-200x. However, the 

1061 utility may create or modify system files, such as log files, that are outside the utility's 

1062 normal execution environment. 


1063 EXTENDED DESCRIPTION 

1064 The EXTENDED DESCRIPTION section provides a place for describing the actions of 

1065 very complicated utilities, such as text editors or language processors, which typically 

1066 have elaborate command languages. 

1067 Default Behavior: When this section is listed as "None.", no further description is 

1068 necessary. 


1069 

1070 

1071 

1072 

1073 

1074 

1075 

1076 


EXIT STATUS 

The EXIT STATUS section describes the values the utility returns to the calling 
program, or shell, and the conditions that cause these values to be returned. Usually, 
utilities return zero for successful completion and values greater than zero for various 
error conditions. If specific numeric values are listed in this section, the system uses 
those values for the errors described. In some cases, status values are listed more 
loosely, such as >0. A portable application cannot rely on any specific value in the I 
range shown and shall be prepared to receive any value in the range. I 
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1077 

1078 

1079 

1080 
1081 
1082 

1083 

1084 

1085 

1086 

1087 

1088 

1089 

1090 

1091 

1092 

1093 

1094 

1095 

1096 

1097 

1098 

1099 

1100 
1101 
1102 

1103 

1104 

1105 

1106 

1107 

1108 

1109 

1110 

1111 

1112 

1113 

1114 

1115 

1116 

1117 

1118 

1119 

1120 


For example, a utility may list zero as a successful return, 1 as a failure for a specific 
reason, and >1 as "an error occurred". In this case, unspecified conditions may cause a 
2 or 3, or other value, to be returned. A portable application should be written so that it 
tests for successful exit status values (zero in this case), rather than relying upon the 
single specific error value listed in this volume of IEEE Std. 1003.1-200x. In that way, it 
has maximum portability, even on implementations with extensions. 

Unspecified error conditions may be represented by specific values not listed in this 
volume of IEEE Std. 1003.1-200x. 

CONSEQUENCES OF ERRORS 

The CONSEQUENCES OF ERRORS section describes the effects on the environment, 
file systems, process state, and so on, when error conditions occur. It does not describe 
error messages produced or exit status values used. 

The many reasons for failure of a utility are generally not specified by the utility 
descriptions. Utilities may terminate prematurely if they encounter: invalid usage of 
options, arguments, or environment variables; invalid usage of the complex syntaxes 
expressed in EXTENDED DESCRIPTION sections; difficulties accessing, creating, 
reading, or writing files; or difficulties associated with the privileges of the process. 

The following apply to each utility, unless otherwise stated: 

• If the requested action cannot be performed on an operand representing a file, 
directory, user, process, and so on, the utility issues a diagnostic message to 
standard error and continues processing the next operand in sequence, but the final 
exit status is returned as non-zero. 

For a utility that recursively traverses a file hierarchy (such as find or chown -R), if 
the requested action cannot be performed on a file or directory encountered in the 
hierarchy, the utility issues a diagnostic message to standard error and continues 
processing the remaining files in the hierarchy, but the final exit status is returned as 
non-zero. 

• If the requested action characterized by an option or option-argument cannot be 
performed, the utility issues a diagnostic message to standard error and the exit 
status returned is non-zero. 

• When an unrecoverable error condition is encountered, the utility exits with a non¬ 
zero exit status. 

• A diagnostic message is written to standard error whenever an error condition 
occurs. 

When a utility encounters an error condition several actions are possible, depending on 
the severity of the error and the state of the utility. Included in the possible actions of 
various utilities are: deletion of temporary or intermediate work files; deletion of 
incomplete files; validity checking of the file system or directory. 

Default Behavior: When this section is listed as "Default.", it means that any changes 
to the environment are unspecified. 

APPLICATION USAGE 

This section is non-normative. 

The APPLICATION USAGE section gives advice to the application programmer or user 
about the way the utility should be used. 
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EXAMPLES 

This section is non-normative. 

The EXAMPLES section gives one or more examples of usage, where appropriate. In 
the event of conflict between an example and a normative part of the specification, the 
normative material is to be taken as correct. 

In all examples, quoting has been used, showing how sample commands (utility names 
combined with arguments) could be passed correctly to a shell (see sh) or as a string to 
the system () function defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 
Such quoting would not be used if the utility is invoked using one of the exec functions 
defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 

RATIONALE 

This section is non-normative. 

This section contains historical information concerning the contents of this volume of 
IEEE Std. 1003.1-200x and why features were included or discarded by the standard 
developers. 

FUTURE DIRECTIONS 

This section is non-normative. 

The FUTURE DIRECTIONS section should be used as a guide to current thinking; there 
is not necessarily a commitment to implement all of these future directions in their 
entirety. 

SEE ALSO 

This section is non-normative. 

The SEE ALSO section lists related entries. 

CHANGE HISTORY 

This section is non-normative. 

The CHANGE HISTORY section shows the derivation of the description used by this 
volume of IEEE Std. 1003.1-200x and lists the functional differences between Issues 4 
and 6. 


1149 Certain of the standard utilities describe how they can invoke other utilities or applications, such 

1150 as by passing a command string to the command interpreter. The external influences (STDIN, 

1151 ENVIRONMENT VARIABLES, and so on) and external effects (STDOUT, CONSEQUENCES OF 

1152 ERRORS, and so on) of such invoked utilities are not described in the section concerning the 

1153 standard utility that invokes them. 
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1154 1.12 Considerations for Utilities in Support of Files of Arbitrary Size 

1155 The following utilities support files of any size up to the maximum that can be created by the 

1156 implementation. This support includes correct writing of file size-related values (such as file 

1157 sizes and offsets, line numbers, and block counts) and correct interpretation of command line 

1158 arguments that contain such values. 


1159 

basename 

Return non-directory portion of path name. 

1160 

cat 

Concatenate and print files. 

1161 

cd 

Change working directory. 

1162 

chgrp 

Change file group ownership. 

1163 

chmod 

Change file modes. 

1164 

chown 

Change file ownership. 

1165 

cksum 

Write file checksums and sizes. 

1166 

cmp 

Compare two files. 

1167 

cp 

Copy files. 

1168 

dd 

Convert and copy a file. 

1169 

df 

Report free disk space. 

1170 

dirname 

Return directory portion of path name. 

1171 

du 

Estimate file space usage. 

1172 

find 

Find files. 

1173 

In 

Link files. 

1174 

Is 

List directory contents. 

1175 

mkdir 

Make directories. 

1176 

mv 

Move files. 

1177 

pathchk 

Check path names. 

1178 

pwd 

Return working directory name. 

1179 

rm 

Remove directory entries. 

1180 

rmdir 

Remove directories. 

1181 

sh 

Shell, the standard command language interpreter. 

1182 

sum 

Print checksum and block or byte count of a file. 

1183 

test 

Evaluate expression. 

1184 

touch 

Change file access and modification times. 

1185 

ulimit 

Set or report file size limit. 


1186 Exceptions to the requirement that utilities support files of any size up to the maximum are: 

1187 1. Uses of files as command scripts, or for configuration or control, are exempt. For example, 

1188 it is not required that sh be able to read an arbitrarily large .profile. 

1189 2. Shell input and output redirection are exempt. For example, it is not required that the 

1190 redirections sum <file or echofoo >file succeed for an arbitrarily large existing file. 
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1193 This chapter contains the definition of the Shell Command Language. 


1194 2.1 Shell Introduction 

1195 The shell is a command language interpreter. This chapter describes the syntax of that command 

1196 language as it is used by the sh utility and the system() and popen() functions defined in the 

1197 System Interfaces volume of IEEE Std. 1003.1-200x. 

1198 The shell operates according to the following general overview of operations. The specific 

1199 details are included in the cited sections of this chapter. 

1200 1. The shell reads its input from a file (see sh), from the -c option or from the system () and 

1201 popen() functions defined in the System Interfaces volume of IEEE Std. 1003.1-200x. If the 

1202 first line of a file of shell commands starts with the characters "#!", the results are 

1203 unspecified. 

1204 2. The shell breaks the input into tokens: words and operators; see Section 2.3 on page 39. 

1205 3. The shell parses the input into simple commands (see Section 2.9.1 on page 67) and 

1206 compound commands (see Section 2.9.4 on page 75). 

1207 4. The shell performs various expansions (separately) on different parts of each command, 

1208 resulting in a list of path names and fields to be treated as a command and arguments; see 

1209 Section 2.6 on page 49. 

1210 5. The shell performs redirection (see Section 2.7 on page 60) and removes redirection 

1211 operators and their operands from the parameter list. 

1212 6. The shell executes a function (see Section 2.9.5 on page 79), built-in (see Section 2.14 on 

1213 page 96), executable file, or script, giving the names of the arguments as positional 

1214 parameters numbered 1 to n, and the name of the command (or in the case of a function 

1215 within a script, the name of the script) as the positional parameter numbered 0 (see Section 

1216 2.9.1.1 on page 69). 

1217 7. The shell optionally waits for the command to complete and collects the exit status (see 

1218 Section 2.8.2 on page 65). 

1219 Rationale 

1220 The System V shell was selected as the starting point for this volume of IEEE Std. 1003.1-200x. 

1221 The BSD C shell was excluded from consideration for the following reasons: 

1222 • Most historically portable shell scripts assume the Version 7 Bourne shell, from which the 

1223 System V shell is derived. 

1224 • The majority of tutorial materials on shell programming assume the System V shell. 

1225 The construct " # ! " is reserved for implementations wishing to provide that extension. If it 

1226 were not reserved, this volume of IEEE Std. 1003.1-200x would disallow it by forcing it to be a 

1227 comment. As it stands, a conforming application must not use " # ! " as the first two characters of 

1228 the file. 
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1229 2.2 Quoting 

1230 Quoting is used to remove the special meaning of certain characters or words to the shell. 

1231 Quoting can be used to preserve the literal meaning of the special characters in the next 

1232 paragraph, prevent reserved words from being recognized as such, and prevent parameter 

1233 expansion and command substitution within here-document processing (see Section 2.7.4 on 

1234 page 61). 

1235 The application shall quote the following characters if they are to represent themselves: I 

1236 f&;<>()$'\"' <space> <tab> <newline> 

1237 and the following may need to be quoted under certain circumstances. That is, these characters 

1238 may be special depending on conditions described elsewhere in this volume of 

1239 IEEE Std. 1003.1-200x: 

1240 * ? [ # ~ = % 

1241 The various quoting mechanisms are the escape character, single-quotes, and double-quotes. 

1242 The here-document represents another form of quoting; see Section 2.7.4 on page 61. 

1243 2.2.1 Escape Character (Backslash) 

1244 A backslash that is not quoted shall preserve the literal value of the following character, with the 

1245 exception of a <newline> character. If a <newline> character follows the backslash, the shell 

1246 shall interpret this as line continuation. The backslash and <newline> characters shall be 

1247 removed before splitting the input into tokens. Since the escaped <newline> character is 

1248 removed entirely from the input and is not replaced by any white space, it cannot serve as a 

1249 token separator. 

1250 2.2.2 Single-Quotes 

1251 Enclosing characters in single-quotes (' ') shall preserve the literal value of each character 

1252 within the single-quotes. A single-quote cannot occur within single-quotes. 

1253 Rationale 

1254 A backslash cannot be used to escape a single-quote in a single-quoted string. An embedded 

1255 quote can be created by writing, for example: "'a' V ' b' ", which yields "a' b". (See Section 

1256 2.6.5 on page 58 for a better understanding of how portions of words are either split into fields or 

1257 remain concatenated.) A single token can be made up of concatenated partial strings containing 

1258 all three kinds of quoting or escaping, thus permitting any combination of characters. 

1259 2.2.3 Double-Quotes 

1260 Enclosing characters in double-quotes (" ") shall preserve the literal value of all characters 

1261 within the double-quotes, with the exception of the characters dollar sign, backquote, and I 

1262 backslash, as follows: 

1263 $ The dollar sign shall retain its special meaning introducing parameter expansion (see I 

1264 Section 2.6.2 on page 51), a form of command substitution (see Section 2.6.3 on page 54), and 

1265 arithmetic expansion (see Section 2.6.4 on page 56). 

1266 The input characters within the quoted string that are also enclosed between " $ (" and the 

1267 matching ' ) ' is not affected by the double-quotes, but rather shall define that command 

1268 whose output replaces the when the word is expanded. The tokenizing rules in 

1269 Section 2.3 on page 39 shall be applied recursively to find the matching ' ) '. 
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1270 

1271 

1272 

1273 


Within the string of characters from an enclosed " $ {" to the matching ' }', an even number 
of unescaped double-quotes or single-quotes, if any, shall occur. A preceding backslash I 
character shall be used to escape a literal ' {' or ' }' • The rule in Section 2.6.2 on page 51 I 
shall be used to determine the matching ' }'. 


1274 

1275 

1276 

1277 

1278 


The backquote shall retain its special meaning introducing the other form of command 
substitution (see Section 2.6.3 on page 54). The portion of the quoted string from the initial 
backquote and the characters up to the next backquote that is not preceded by a backslash, 
having escape characters removed, defines that command whose output replaces " '. . . '" 
when the word is expanded. Either of the following cases produces undefined results: 


1279 • A single-quoted or double-quoted string that begins, but does not end, within the 

1280 " '. . . '" sequence 


1281 • A " sequence that begins, but does not end, within the same double-quoted 

1282 string 


1283 \ The backslash shall retain its special meaning as an escape character (see Section 2.2.1 on 

1284 P a g e 36) only when followed by one of the following characters when considered special: 


1285 


$ ' " \ <newline> 


1286 The application shall ensure that a double-quote is preceded by a backslash to be included I 

1287 within double-quotes. The parameter ' @' has special meaning inside double-quotes and is I 

1288 described in Section 2.5.2 on page 43. 

1289 Rationale 

1290 The escaped <newline> used for line continuation is removed entirely from the input and is not 

1291 replaced by any white space. Therefore, it cannot serve as a token separator. 

1292 In double-quoting, if a backslash is immediately followed by a character that would be 

1293 interpreted as having a special meaning, the backslash is deleted and the subsequent character is 

1294 taken literally. If a backslash does not precede a character that would have a special meaning, it 

1295 is left in place unmodified and the character immediately following it is also left unmodified. 

1296 Thus, for example: 

1297 "\$" -> $ 

1298 " \ a" \a 

1299 It would be desirable to include the statement "The characters from an enclosed " $ {" to the 

1300 matching ' }' shall not be affected by the double quotes", similar to the one for " $ () ". 

1301 However, historical practice in the System V shell prevents this. 

1302 The requirement that double-quotes be matched inside within double-quotes and the 

1303 rule for finding the matching ' }' in Section 2.6.2 on page 51 eliminate several subtle 

1304 inconsistencies in expansion for historical shells in rare cases; for example: 

1305 " $ { foo-bar " } 

1306 yields bar when too is not defined, and is an invalid substitution when too is defined, in many 

1307 historical shells. The differences in processing the form have led to inconsistencies 

1308 between historical systems. A consequence of this rule is that single-quotes cannot be used to 

1309 quote the ' }' within for example: 

1310 unset bar 

1311 foo="$ {bar-' }' } " 
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1312 is invalid because the substitution contains an unpaired unescaped single-quote. The 

1313 backslash can be used to escape the ' }' in this example to achieve the desired result: 

1314 unset bar 

1315 foo=" $ {bar—\ } } " 

1316 The differences in processing the form have led to inconsistencies between the 

1317 historical System V shell, BSD, and KomShells, and the text in this volume of 

1318 IEEE Std. 1003.1-200x is an attempt to converge them without breaking too many applications. 

1319 The only alternative to this compromise between shells would be to make the behavior 

1320 unspecified whenever the literal characters ' ' ', ' {', ' }', and ' "' appear within 

1321 To write a portable script that uses these values, a user would have to assign variables, for 

1322 example: 

1323 squote=V dquote=\" lbrace='{' rbrace='}' 

1324 $ { foo—$squote$rbrace$squote } 

1325 rather than: 

1326 ${foo-"'}'"} 

1327 Some systems have allowed the end of the word to terminate the backquoted command 

1328 substitution, such as in: 

1329 " 'echo hello" 

1330 This usage is undefined; the matching backquote is required by this volume of 

1331 IEEE Std. 1003.1-200x. The other undefined usage can be illustrated by the example: 

1332 sh — c ' ' echo "foo'' 

1333 The description of the recursive actions involving command substitution can be illustrated with 

1334 an example. Upon recognizing the introduction of command substitution, the shell parses input I 

1335 (in a new context), gathering the source for the command substitution until an unbalanced ' )' I 

1336 or ' '' is located. For example, in the following: 

1337 echo "$(date; echo " 

1338 one " ) " 

1339 the double-quote following the echo does not terminate the first double-quote; it is part of the 

1340 command substitution script. Similarly, in: 

1341 echo "$ (echo *) " 

1342 the asterisk is not quoted since it is inside command substitution; however: 

1343 echo " $ (echo 

1344 is quoted (and represents the asterisk character itself). 
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1345 2.3 Token Recognition 

1346 The shell reads its input in terms of lines from a file, from a terminal in the case of an interactive 

1347 shell, or from a string in the case of sh -c or system (). The input lines can be of unlimited length. 

1348 These lines are parsed using two major modes: ordinary token recognition and processing of 

1349 here-documents. 


1350 When an io_here token has been recognized by the grammar (see Section 2.10 on page 82), one 

1351 or more of the subsequent lines immediately following the next NEWLINE token form the body 

1352 of one or more here-documents and shall be parsed according to the rules of Section 2.7.4 on 

1353 page 61. 

1354 When it is not processing an io_here, the shell shall break its input into tokens by applying the 

1355 first applicable rule below to the next character in its input. The token shall be from the current 

1356 position in the input until a token is delimited according to one of the rules below; the characters 

1357 forming the token are exactly those in the input, including any quoting characters. If it is 

1358 indicated that a token is delimited, and no characters have been included in a token, processing 

1359 shall continue until an actual token is delimited. 


1360 

1361 


1. If the end of input is recognized, the current token shall be delimited. If there is no current 
token, the end-of-input indicator shall be returned as the token. 


1362 

1363 

1364 


2. If the previous character was used as part of an operator and the current character is not 
quoted and can be used with the current characters to form an operator, it shall be used as 
part of that (operator) token. 


1365 

1366 

1367 

1368 


Note that certain combinations of characters are invalid in portable scripts, as shown in the 
grammar, and that some systems have assigned these combinations (such as " | & ") as 
valid control operators. Portable scripts cannot rely on receiving errors in all cases where 
this volume of IEEE Std. 1003.1-200x indicates that a syntax is invalid. 


1369 

1370 

1371 


3. If the previous character was used as part of an operator and the current character cannot 
be used with the current characters to form an operator, the operator containing the 
previous character shall be delimited. 


1372 

1373 

1374 

1375 

1376 

1377 

1378 

1379 


4. If the current character is backslash, single-quote, or double-quote (' \', ''', or ' ) ' and 
it is not quoted, it shall affect quoting for subsequent characters up to the end of the quoted 
text. The rules for quoting are as described in Section 2.2 on page 36. During token 
recognition no substitutions shall be actually performed, and the result token shall contain 
exactly the characters that appear in the input (except for <newline> character joining), 
unmodified, including any embedded or enclosing quotes or substitution operators, 
between the quote mark and the end of the quoted text. The token shall not be delimited by 
the end of the quoted field. 


1380 

1381 

1382 

1383 

1384 

1385 

1386 

1387 

1388 

1389 

1390 

1391 


5. If the current character is an unquoted ' $' or ' '', the shell shall identify the start of any 
candidates for parameter expansion (Section 2.6.2 on page 51), command substitution 
(Section 2.6.3 on page 54), or arithmetic expansion (Section 2.6.4 on page 56) from their 
introductory unquoted character sequences: '$' or "${", "$(" or ' '', and "$((", 
respectively. The shell shall read sufficient input to determine the end of the unit to be 
expanded (as explained in the cited sections). While processing the characters, if instances 
of expansions or quoting are found nested within the substitution, the shell shall 
recursively process them in the manner specified for the construct that is found. The 
characters found from the beginning of the substitution to its end, allowing for any 
recursion necessary to recognize embedded constructs, shall be included unmodified in the 
result token, including any embedded or enclosing substitution operators or quotes. The 
token shall not be delimited by the end of the substitution. 
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1392 

1393 

1394 


6. If the current character is not quoted and can be used as the first character of a new 
operator, the current token (if any) shall be delimited. The current character shall be used 
as the beginning of the next (operator) token. 


1395 7. If the current character is an unquoted <newline> character, the current token shall be 

1396 delimited. 


1397 8. If the current character is an unquoted <blank> character, any token containing the 

1398 previous character is delimited and the current character shall be discarded. 


1399 9. If the previous character was part of a word, the current character shall be appended to 

1400 that word. 


1401 

1402 

1403 

1404 

1405 


10. If the current character is a ' #', it and all subsequent characters up to, but excluding, the 
next <newline> character shall be discarded as a comment. The <newline> character that 
ends the line is not considered part of the comment. The ' #' starts a comment only when 
it is at the beginning of a token. Since the search for the end-of-comment does not consider 
an escaped <newline> character specially, a comment cannot be continued to the next line. 


1406 


11. The current character is used as the start of a new word. 


1407 Once a token is delimited, it is categorized as required by the grammar in Section 2.10 on page 

1408 82. 


1409 Rationale 

1410 The (3) rule about combining characters to form operators is not meant to preclude systems from 

1411 extending the shell language when characters are combined in otherwise invalid ways. Portable 

1412 applications cannot use invalid combinations, and test suites should not penalize systems that 

1413 take advantage of this fact. For example, the unquoted combination " | & " is not valid in a POSIX 

1414 script, but has a specific KomShell meaning. 

1415 The (10) rule about ' #' as the current character is the first in the sequence in which a new token 

1416 is being assembled. The ' #' starts a comment only when it is at the beginning of a token. This 

1417 rule is also written to indicate that the search for the end-of-comment does not consider escaped 

1418 <newline> specially, so that a comment cannot be continued to the next line. 


1419 2.3.1 Alias Substitution 

1420 up xsi The processing of aliases shall be supported on all XSI-conformant systems or if the system 

1421 supports the User Portability Utilities option. 

1422 After a token has been delimited, but before applying the grammatical rules in Section 2.10 on 

1423 P a g e 82, a resulting word that is identified to be the command name word of a simple command 

1424 shall be examined to determine whether it is an unquoted, valid alias name. However, reserved 

1425 words in correct grammatical context shall not be candidates for alias substitution. A valid alias I 

1426 name (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.10, Alias I 

1427 Name) shall be one that has been defined by the alias utility and not subsequently undefined I 

1428 using unalias. Implementations also may provide predefined valid aliases that are in effect when 

1429 the shell is invoked. To prevent infinite loops in recursive aliasing, if the shell is not currently 

1430 processing an alias of the same name, the word shall be replaced by the value of the alias; 

1431 otherwise, it shall not be replaced. 

1432 If the value of the alias replacing the word ends in a <blank> character, the shell shall check the 

1433 next command word for alias substitution; this process shall continue until a word is found that 

1434 is not a valid alias or an alias value does not end in a <blank> character. 
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1435 When used as specified by this volume of IEEE Std. 1003.1-200x, alias definitions shall not be 

1436 inherited by separate invocations of the shell or by the utility execution environments invoked 

1437 by the shell; see Section 2.12 on page 90. 

1438 Rationale 

1439 The alias capability was added in the UPE because it is widely used in historical 

1440 implementations by interactive users. It was omitted from the base standard because it is not 

1441 commonly used in application scripts, particularly since aliases are not passed to child shells. 

1442 The definition of alias name precludes an alias name containing a slash character. Since the text 

1443 applies to the command words of simple commands, reserved words (in their proper places) 

1444 cannot be confused with aliases. 

1445 The placement of alias substitution in Token Recognition makes it clear that it precedes all of the 

1446 word expansion steps. 

1447 An example concerning trailing <blank> characters and reserved words follows. If the user 

1448 types: 

1449 $ alias foo="/bin/ls " 

1450 $ alias while="/" 

1451 The effect of executing: 

1452 $ while true 

1453 > do 

1454 > echo "Hello, World" 

1455 > done 

1456 is a never-ending sequence of "Hello, World" strings to the screen. However, if the user 

1457 types: 

1458 $ foo while 

1459 the result is an Is listing of /. Since the alias substitution for foo ends in a <space> character, the 

1460 next word is checked for alias substitution. The next word, while, has also been aliased, so it is 

1461 substituted as well. Since it is not in the proper position as a command word, it is not recognized 

1462 as a reserved word. 

1463 If the user types: 

1464 $ foo; while 

1465 while retains its normal reserved-word properties. 
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1466 2.4 Reserved Words 

1467 Reserved words are words that have special meaning to the shell; see Section 2.9 on page 67. 

1468 The following words shall be recognized as reserved words: 


1469 

! 

do 

esac 

in 

1470 

{ 

done 

fi 

then 

1471 

} 

elif 

for 

until 

1472 

case 

else 

if 

while 


1473 This recognition shall only occur when none of the characters is quoted and when the word is 

1474 used as: 

1475 • The first word of a command 

1476 • The first word following one of the reserved words other than case, for, or in 

1477 • The third word in a case or for command (only in is valid in this case) 

1478 See the grammar in Section 2.10 on page 82. 

1479 The following words may be recognized as reserved words on some systems (when none of the 

1480 characters are quoted), causing unspecified results: 

1481 [ [ ] ] function select 

1482 Words that are the concatenation of a name and a colon (' :') are reserved; their use produces 

1483 unspecified results. This reservation is to allow future implementations that support named 

1484 labels for flow control. 

1485 Rationale 

1486 All reserved words are recognized syntactically as such in the contexts described. However, note 

1487 that in is the only meaningful reserved word after a case or for; similarly, in is not meaningful as 

1488 the first word of a simple command. 

1489 Reserved words are recognized only when they are delimited (that is, meet the definition of the I 

1490 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.432, Word), whereas I 

1491 operators are themselves delimiters. For instance, ' (' and ' ) ' are control operators, so that no I 

1492 <space> character is needed in (list). However, ' {' and ' }' are reserved words in { list ;}, so that 

1493 in this case the leading <space> character and semicolon are required. 

1494 The list of unspecified reserved words is from the KomShell, so portable applications cannot use 

1495 them in places a reserved word would be recognized. This list contained time in early proposals, 

1496 but it was removed when the time utility was selected for this volume of IEEE Std. 1003.1-200x. 

1497 There was a strong argument for promoting braces to operators (instead of reserved words), so 

1498 they would be syntactically equivalent to subshell operators. Concerns about compatibility 

1499 outweighed the advantages of this approach. Nevertheless, portable applications should 

1500 consider quoting ' {' and ' }' when they represent themselves. 

1501 The restriction on ending a name with a colon is to allow future implementations that support 

1502 named labels for flow control. See the RATIONALE for break on page 97. 

1503 It is possible that a future version of this volume of IEEE Std. 1003.1-200x may require that ' {' 

1504 and ' }' be treated individually as control operators, although the token " { }" will probably be 

1505 a special-case exemption from this because of the often-used/mdj} construct. 
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1506 2.5 Parameters and Variables 

1507 A parameter can be denoted by a name, a number, or one of the special characters listed in 

1508 Section 2.5.2. A variable is a parameter denoted by a name. 

1509 A parameter is set if it has an assigned value (null is a valid value). Once a variable is set, it can 

1510 only be unset by using the unset special built-in command. 

1511 2.5.1 Positional Parameters 

1512 A positional parameter is a parameter denoted by the decimal value represented by one or more 

1513 digits, other than the single digit 0. The digits denoting the positional parameters are always 

1514 interpreted as a decimal value, even if there is a leading zero. When a positional parameter with I 

1515 more than one digit is specified, the application shall enclose the digits in braces (see Section I 

1516 2.6.2 on page 51). Positional parameters are initially assigned when the shell is invoked (see sh), 

1517 temporarily replaced when a shell function is invoked (see Section 2.9.5 on page 79), and can be 

1518 reassigned with the set special built-in command. 

1519 Rationale 

1520 The digits denoting the positional parameters are always interpreted as a decimal value, even if 

1521 there is a leading zero. 

1522 2.5.2 Special Parameters 

1523 Listed below are the special parameters and the values to which they shall expand. Only the 

1524 values of the special parameters are listed; see Section 2.6 on page 49 for a detailed summary of 

1525 all the stages involved in expanding words. 

1526 @ Expands to the positional parameters, starting from one. When the expansion occurs within 

1527 double-quotes, and where field splitting (see Section 2.6.5 on page 58) is performed, each 

1528 positional parameter expands as a separate field, with the provision that the expansion of 

1529 the first parameter is still joined with the beginning part of the original word (assuming that 

1530 the expanded parameter was embedded within a word), and the expansion of the last 

1531 parameter is still joined with the last part of the original word. If there are no positional 

1532 parameters, the expansion of ' @' generates zero fields, even when ' @ ' is double-quoted. 

1533 * Expands to the positional parameters, starting from one. When the expansion occurs within 

1534 a double-quoted string (see Section 2.2.3 on page 36), it expands to a single field with the 

1535 value of each parameter separated by the first character of the IFS variable, or by a <space> 

1536 character if IFS is unset. If IFS is set to a null string, this is not equivalent to unsetting it; its 

1537 first character does not exist, so the parameter values are concatenated. 

1538 # Expands to the decimal number of positional parameters. The command name (parameter 

1539 0) is not counted in the number given by ' #' because it is a special parameter, not a 

1540 positional parameter. 

1541 ? Expands to the decimal exit status of the most recent pipeline (see Section 2.9.2 on page 72). 

1542 - (Hyphen.) Expands to the current option flags (the single-letter option names concatenated 

1543 into a string) as specified on invocation by the set special built-in command or implicitly by 

1544 the shell. 

1545 $ Expands to the decimal process ID of the invoked shell. In a subshell (see Section 2.12 on 

1546 P a g e 90), ' $' shall expand to the same value as that of the current shell. 
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1547 Most historical implementations implement subshells by forking; thus, the special 

1548 parameter ' $' does not necessarily represent the process ID of the shell process executing 

1549 the commands since the subshell execution environment preserves the value of ' $'. 

1550 ! Expands to the decimal process ID of the most recent background command (see Section 

1551 2.9.3 on page 73) executed from the current shell. (For example, background commands 

1552 executed from subshells do not affect the value of " $ !" in the current shell environment.) 

1553 For a pipeline, the process ID is that of the last command in the pipeline. 

1554 0 (Zero.) Expands to the name of the shell or shell script. See sh on page 888 for a detailed 

1555 description of how this name is derived. 

1556 See the description of the IFS variable in Section 2.5.3 on page 45. 

1557 Rationale 

1558 Most historical implementations implement subshells by forking; thus, the special parameter 

1559 ' $' does not necessarily represent the process ID of the shell process executing the commands 

1560 since the subshell execution environment preserves the value of ' $'. 

1561 If a subshell were to execute a background command, the value of " $ !" for the parent would 

1562 not change. For example: 

1563 ( 

1564 date & 

1565 echo $ ! 

1566 ) 

1567 echo $ ! 

1568 would echo two different values for " $ !". 

1569 The " $-" special parameter can be used to save and restore set options: 

1570 Save=$ (echo $- | sed ' s/[ics] //q' ) 

1571 

1572 set +aCefnuvx 

1573 if [ —n "$Save" ]; then 

1574 set —$Save 

1575 fi 

1576 The three options are removed using sed in the example because they may appear in the value of 

1577 " $-" (from the sh command line), but are not valid options to set. 

1578 The descriptions of parameters ' *' and ' @' assume the reader is familiar with the field splitting 

1579 discussion in Section 2.6.5 on page 58 and understands that portions of the word remain 

1580 concatenated unless there is some reason to split them into separate fields. 

1581 Some examples of the ' *' and ' @' properties, including the concatenation aspects: 


1582 

set " 

abc" 

"def ghi" "jkl" 


1583 

echo 

$* 

=> "abc" "def" "ghi" 

" jkl 

1584 

echo 

" $ * " 

=> "abc def ghi jkl" 


1585 

echo 

$@ 

=> "abc" "def" "ghi" 

" jkl 


1586 but: 
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1587 

echo 


= > 

" abc" 

"def ghi" " 

jkl" 

1588 

echo 

"xx$@yy" 

= > 

"xxabc 

" "def ghi" 

"jklyy" 

1589 

echo 

"$@$@" 

= > 

"abc" 

"def ghi" " 

jklabc" "def ghi" "jkl" 


1590 In the preceding examples, the double-quote characters that appear after the "=> " do not appear 

1591 in the output and are used only to illustrate word boundaries. 

1592 The following example illustrates the effect of setting IFS to a null string: 


1593 

1594 

1595 

1596 

1597 

1598 

1599 

1600 
1601 


$ IFS='' 

$ set foo bar bam 
$ echo "$@" 

foo bar bam 

$ echo "$*" 

foobarbam 

$ unset IFS 
$ echo "$*" 

foo bar bam 


1602 2.5.3 Shell Variables 


1603 

1604 

1605 

1606 

1607 

1608 

1609 

1610 


Variables shall be initialized from the environment (as defined by the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables and the exec I 
function in the System Interfaces volume of IEEE Std. 1003.1-200x) and can be given new values 
with variable assignment commands. If a variable is initialized from the environment, it shall be 
marked for export immediately; see the export special built-in. New variables can be defined and 
initialized with variable assignments, with the read or getopts utilities, with the name parameter in 
a for loop, with the ${name=word j expansion, or with other mechanisms provided as 
implementation extensions. The following variables shall affect the execution of the shell: 


1611 ENV 

1612 

1613 

1614 

1615 

1616 

1617 

1618 
1619 


This variable, when and only when an interactive shell is invoked, shall be I 
subjected to parameter expansion (see Section 2.6.2 on page 51) by the shell I 
and the resulting value shall be used as a path name of a file containing shell 
commands to execute in the current environment. The file need not be 
executable. If the expanded value of ENV is not an absolute path name, the 
results are unspecified. ENV shall be ignored if the user's real and effective 
user IDs or real and effective group IDs are different. This volume of 
IEEE Std. 1003.1-200x specifies the effects of this variable only for systems 
supporting the User Portability Utilities option. 


1620 HOME 

1621 
1622 


This variable shall be interpreted as the path name of the user's home 
directory. The contents of HOME are used in tilde expansion (see Section 2.6.1 
on page 50). 


1623 IFS 

1624 

1625 

1626 


(Input Field Separators.) A string treated as a list of characters that is used for 
field splitting and to split lines into fields with the read command. If IFS is not 
set, the shell shall behave as if the value of IFS were the <space>, <tab>, and 
<newline> characters; see Section 2.6.5 on page 58. 


1627 LANG 

1628 

1629 

1630 

1631 


This variable shall provide a default value for the internationalization 
variables that are unset or null. If LANG is unset or null, the corresponding 
value from the implementation-dependent default locale is used. If any of the 
internationalization variables contains an invalid setting, the utility behaves as 
if none of the variables had been defined. 


1632 

1633 


LC_ALL This variable shall provide a default value for the LC_* variables, as described I 

in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter I 
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1634 


8, Environment Variables. 


1635 LC_COLLATE This variable shall determine the behavior of range expressions, equivalence 

1636 classes, and multi-character collating elements within pattern matching. 


1637 

1638 

1639 

1640 

1641 

1642 

1643 

1644 

1645 


LC_CTYPE This variable shall determine the interpretation of sequences of bytes of text 

data as characters (for example, single-byte as opposed to multi-byte 
characters), which characters are defined as letters (character class alpha) and 
<blank> characters (character class blank), and the behavior of character 
classes within pattern matching. Changing the value of LCJCTYPE after the 
shell has started shall not affect the lexical processing of shell commands in 
the current shell execution environment or its subshells. Invoking a shell 
script or performing exec sh subjects the new shell to the changes in 
LCjCTYPE. 


1646 LC_MESSAGES This variable shall determine the language in which messages should be 

1647 written. 


1648 LINENO This variable shall be set by the shell to a decimal number representing the 

1649 current sequential line number (numbered starting with 1) within a script or 

1650 function before it executes each command. If the user unsets or resets 

1651 LINENO, the variable may lose its special meaning for the life of the shell. If 

1652 the shell is not currently executing a script or function, the value of LINENO is 

1653 unspecified. This volume of IEEE Std. 1003.1-200x specifies the effects of the 

1654 variable only for systems supporting the User Portability Utilities option. 


1655 xsi NLSPATH This variable shall determine the location of message catalogs for the 

1656 processing of LC_MESSAGES. 


1657 PATH 

1658 

1659 

1660 


This variable represents a string formatted as described in the System I 
Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment I 
Variables, used to effect command interpretation; see Section 2.9.1.1 on page I 
69. 


1661 PPID 

1662 

1663 

1664 

1665 

1666 


This variable shall be set by the shell to the decimal process ID of the process 
that invoked this shell. In a subshell (see Section 2.12 on page 90), PPID shall 
be set to the same value as that of the parent of the current shell. For example, 
echo$PPID and (echo$PPID) would produce the same value. This volume of 
IEEE Std. 1003.1-200x specifies the effects of the variable only for systems 
supporting the User Portability Utilities option. 


1667 PS1 

1668 

1669 

1670 

1671 

1672 

1673 

1674 

1675 

1676 


Each time an interactive shell is ready to read a command, the value of this 
variable shall be subjected to parameter expansion and written to standard 
error. The default value shall be " $ ". For users who have specific additional 
implementation-dependent privileges, the default may be another, 
implementation-dependent value. (Historically, the superuser has had a 
prompt of ' #'.) The shell shall replace each instance of the character ' !' in 
PS1 with the history file number of the next command to be typed. Escaping 
the ' ! ' with another ' ! ' (that is, " ! ! ") shall place the literal character ' ! ' 
in the prompt. This volume of IEEE Std. 1003.1-200x specifies the effects of the 
variable only for systems supporting the User Portability Utilities option. 


1677 PS2 

1678 

1679 

1680 
1681 


Each time the user enters a <newline> character prior to completing a 
command line in an interactive shell, the value of this variable shall be 
subjected to parameter expansion and written to standard error. The default 
value is " > ". This volume of IEEE Std. 1003.1-200x specifies the effects of the 
variable only for systems supporting the User Portability Utilities option. 
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1682 PS4 

1683 

1684 

1685 

1686 


When an execution trace (set -x) is being performed in an interactive shell, 
before each line in the execution trace, the value of this variable shall be 
subjected to parameter expansion and written to standard error. The default 
value is " + ". This volume of IEEE Std. 1003.1-200x specifies the effects of the 
variable only for systems supporting the User Portability Utilities option. 


1687 PWD 

1688 

1689 

1690 

1691 


This variable shall be set by the shell to be an absolute path name of the 
current working directory, containing no components of type symbolic link, 
no components that are dot, and no components that are dot-dot when the 
shell is initialized. If an application sets or unsets the value of PWD, the 
behaviors of the cd and pivd utilities are unspecified. 


1692 Rationale 

1693 See the discussion of IPS in Rationale on page 58. 

1694 The prohibition on LC_CTYPE changes affecting lexical processing protects the shell 

1695 implementor (and the shell programmer) from the ill effects of changing the definition of 

1696 <blank> or the set of alphabetic characters in the current environment. It would probably not be 

1697 feasible to write a compiled version of a shell script without this rule. The rule applies only to 

1698 the current invocation of the shell and its subshells—invoking a shell script or performing exec sh 

1699 would subject the new shell to the changes in LCJCTYPE. 

1700 Other common environment variables used by historical shells are not specified by this volume 

1701 of IEEE Std. 1003.1-200x, but they should be reserved for the historical uses. 

1702 Tilde expansion for components of the PATH in an assignment such as: 

1703 PATH= ~hl j /bin : 'dwc/bin : $PATH 

1704 is a feature of some historical shells and is allowed by the wording of Section 2.6.1 on page 50. 

1705 Note that the tildes are expanded during the assignment to PATH, not when PATH is accessed 

1706 during command search. 

1707 The following entries represent additional information about variables included in this volume 

1708 of IEEE Std. 1003.1-200x, or rationale for common variables in use by shells that have been 

1709 excluded: 


1710 

1711 

1712 


(Underscore.) While underscore is historical practice, its overloaded usage in 
the KomShell is confusing, and it has been omitted from this volume of 


IEEE Std. 1003.1-200x. 


1713 ENV 

1714 

1715 

1716 

1717 

1718 

1719 

1720 


This variable can be used to set aliases and other items local to the invocation 
of a shell. The file referred to by ENV differs from $HOME/.profile in that 
.profile is typically executed at session start-up, whereas the ENV file is I 
executed at the beginning of each shell invocation. The ENV value is 
interpreted in a manner similar to a dot script, in that the commands are 
executed in the current environment and the file needs to be readable, but not 
executable. However, unlike dot scripts, no PATH searching is performed. 
This is used as a guard against Trojan Horse security breaches. 


1721 

1722 

1723 


ERRNO This variable was omitted from this volume of IEEE Std. 1003.1-200x because 

the values of error numbers are not defined in the System Interface Definitions 
volume of IEEE Std. 1003.1-200x in a portable manner. 


1724 

1725 

1726 


TCEDIT Since this variable affects only the fc utility, it has been omitted from this more 

global place. The value of FCEDIT does not affect the command line editing I 
mode in the shell; see the description of set -o vi in set on page 117. I 
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1727 

1728 

1729 

1730 

1731 


1732 

PS3 

This variable is used by the KomShell for the select command. Since the POSIX 

1733 


shell does not include select, PS3 was omitted. 

1734 

PS4 

This variable is used for shell debugging. For example, the following script: 

1735 


PS4=' [$ {LINENO}]+ ' 

1736 


set —x 

1737 


echo Hello 

1738 


writes the following to standard error: 

1739 


[3] + echo Hello 

1740 

RANDOM 

This pseudo-random number generator was not seen as being useful to 

1741 


interactive users. 

1742 

SECONDS 

Although this variable is sometimes used with PS1 to allow the display of the 

1743 


current time in the prompt of the user, it is not one that would be manipulated 

1744 


frequently enough by an interactive user to include in this volume of 

1745 


IEEE Std. 1003.1-200x. 


PS1 This variable is used for interactive prompts. Historically, the "superuser" 

has had a prompt of ' #'. Since privileges are not required to be monolithic, it 
is difficult to define which privileges should cause the alternate prompt. 
However, a sufficiently powerful user should be reminded of that power by 
having an alternate prompt. 
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1746 2.6 Word Expansions 

1747 This section describes the various expansions that are performed on words. Not all expansions 

1748 are performed on every word, as explained in the following sections. 

1749 Tilde expansions, parameter expansions, command substitutions, arithmetic expansions, and 

1750 quote removals that occur within a single word expand to a single field. It is only field splitting 

1751 or path name expansion that can create multiple fields from a single word. The single exception 

1752 to this rule is the expansion of the special parameter ' @' within double-quotes, as described in 

1753 Section 2.5.2 on page 43. 

1754 The order of word expansion shall be as follows: 

1755 1. Tilde expansion (see Section 2.6.1 on page 50), parameter expansion (see Section 2.6.2 on 

1756 page 51), command substitution (see Section 2.6.3 on page 54), and arithmetic expansion 

1757 (see Section 2.6.4 on page 56) shall be performed, beginning to end. See item 5 in Section 2.3 

1758 on page 39. 

1759 2. Field splitting (see Section 2.6.5 on page 58) shall be performed on the portions of the fields 

1760 generated by step 1, unless IFS is null. 

1761 3. Path name expansion (see Section 2.6.6 on page 59) shall be performed, unless set -f is in 

1762 effect. 

1763 4. Quote removal (see Section 2.6.7 on page 59) shall always be performed last. 

1764 The expansions described in this section shall occur in the same shell environment as that in 

1765 which the command is executed. 

1766 If the complete expansion appropriate for a word results in an empty field, that empty field shall 

1767 be deleted from the list of fields that form the completely expanded command, unless the 

1768 original word contained single-quote or double-quote characters. 

1769 The ' $' character is used to introduce parameter expansion, command substitution, or 

1770 arithmetic evaluation. If an unquoted ' $' is followed by a character that is either not numeric, 

1771 the name of one of the special parameters (see Section 2.5.2 on page 43), a valid first character of 

1772 a variable name, a left curly brace (' {') or a left parenthesis, the result is unspecified. 

1773 Rationale 

1774 Step (2) refers to the "portions of fields generated by step (1)". For example, if the word being 

1775 expanded were "$x+$y" and IFS=+, the word would be split only if "$x" or "$y" contained 

1776 ' +'; the ' +' in the original word was not generated by step (1). 

1777 IFS is used for performing field splitting on the results of parameter and command substitution; 

1778 it is not used for splitting all fields. Previous versions of the shell used it for splitting all fields 

1779 during field splitting, but this has severe problems because the shell can no longer parse its own 

1780 script. There are also important security implications caused by this behavior. All useful 

1781 applications of IFS use it for parsing input of the read utility and for splitting the results of 

1782 parameter and command substitution. 

1783 The rule concerning expansion to a single field requires that if foo=abc and bar=def, that: 

1784 " $foo" " $bar " 

1785 expands to the single field: 

1786 abode f 
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1787 The rule concerning empty fields can be illustrated by: 

1788 $ unset foo 

1789 $ set $foo bar '' xyz "$foo" abc 

1790 $ for i 

1791 > do 

1792 > echo $i—" 

1793 > done 

1794 -bar- 

1795 — 

1796 —xyz— 

1797 — 

1798 -abc- 

1799 Step (1) indicates that parameter expansion, command substitution, and arithmetic expansion 

1800 are all processed simultaneously as they are scanned. For example, the following is valid 

1801 arithmetic: 

1802 x— 1 

1803 echo $(( $ (echo 3)+$x )) 

1804 An early proposal stated that tilde expansion preceded the other steps, but this is not the case in 

1805 known historical implementations; if it were, and if a referenced home directory contained a ' $' 

1806 character, expansions would result within the directory name. 

1807 2.6.1 Tilde Expansion 

1808 A tilde-prefix consists of an unquoted tilde character at the beginning of a word, followed by all 

1809 of the characters preceding the first unquoted slash in the word, or all the characters in the word 

1810 if there is no slash. In an assignment (see the System Interface Definitions volume of I 

1811 IEEE Std. 1003.1-200x, Section 3.426, Variable Assignment), multiple tilde-prefixes can be used: at I 

1812 the beginning of the word (that is, following the equal sign of the assignment), following any I 

1813 unquoted colon, or both. A tilde-prefix in an assignment is terminated by the first unquoted 

1814 colon or slash. If none of the characters in the tilde-prefix are quoted, the characters in the tilde- 

1815 prefix following the tilde are treated as a possible login name from the user database. A portable 

1816 login name cannot contain characters outside the set given in the description of the LOGNAME I 

1817 environment variable in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

1818 Section 8.3, Other Environment Variables. If the login name is null (that is, the tilde-prefix I 

1819 contains only the tilde), the tilde-prefix is replaced by the value of the variable HOME. If HOME 

1820 is unset, the results are unspecified. Otherwise, the tilde-prefix is replaced by a path name of the 

1821 initial working directory associated with the login name obtained using the getpivnam( ) function 

1822 as defined in the System Interfaces volume of IEEE Std. 1003.1-200x. If the system does not 

1823 recognize the login name, the results are undefined. 


1824 Rationale 

1825 Tilde expansion generally occurs only at the beginning of words, but an exception based on 

1826 historical practice has been included: 

1827 PATH=/posix/bin: ~dgk/bin 

1828 This is eligible for tilde expansion because tilde follows a colon and none of the relevant 

1829 characters is quoted. Consideration was given to prohibiting this behavior because any of the 

1830 following are reasonable substitutes: 
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1831 PATH=$ (printf %s ~karels/bin : ~bostic/bin) 

1832 for Dir in “maart/bin “srb/bin . . . 

1833 do 

1834 PATH=$ { PATH : +$PATH : } $Dir 

1835 done 

1836 In the first command, explicit colons are used for each directory. In all cases, the shell performs 

1837 tilde expansion on each directory because all are separate words to the shell. 

1838 Note that expressions in operands such as: 

1839 make —k mumble LIBDIR=~chet/lib 

1840 do not qualify as shell variable assignments and tilde expansion is not performed (unless the 

1841 command does so itself, which make does not). 

1842 Because of the requirement that the word is not quoted, the following are not equivalent; only 

1843 the last causes tilde expansion: 

1844 \ ~hl j / ~h\l j / ~"hl j"/ ~hlj\/ ~hl j / 

1845 In an early proposal, tilde expansion occurred following any unquoted equals sign or colon, but 

1846 this was removed because of its complexity and to avoid breaking commands such as: 

1847 rep hostname : “marc/ . prof ile . 

1848 A suggestion was made that the special sequence " $ ~" should be allowed to force tilde 

1849 expansion anywhere. Since this is not historical practice, it has been left for future 

1850 implementations to evaluate. (The description in Section 2.2 on page 36 requires that a dollar 

1851 sign be quoted to represent itself, so the " $ ~" combination is already unspecified.) 

1852 The results of giving tilde with an unknown login name are undefined because the KomShell 

1853 " anc ] « constructs make use of this condition, but in general it is an error to give an 

1854 incorrect login name with tilde. The results of having HOME unset are unspecified because some 

1855 historical shells treat this as an error. 

1856 2.6.2 Parameter Expansion 

1857 The format for parameter expansion is as follows: 

1858 ${ expression} 

1859 where expression consists of all characters until the matching ' }'. Any ' }' escaped by a 

1860 backslash or within a quoted string, and characters in embedded arithmetic expansions, 

1861 command substitutions, and variable expansions, shall not be examined in determining the 

1862 matching ' }'. 

1863 The simplest form for parameter expansion is: 

1864 $ {parameter} 

1865 The value, if any, of parameter shall be substituted. 

1866 The parameter name or symbol can be enclosed in braces, which are optional except for 

1867 positional parameters with more than one digit or when parameter is followed by a character that 

1868 could be interpreted as part of the name. The matching closing brace shall be determined by 

1869 counting brace levels, skipping over enclosed quoted strings, and command substitutions. 

1870 If the parameter name or symbol is not enclosed in braces, the expansion shall use the longest I 

1871 valid name (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.234, I 

1872 Name), whether or not the symbol represented by that name exists. I 
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1873 If a parameter expansion occurs inside double-quotes: 

1874 • Path name expansion shall not be performed on the results of the expansion. 

1875 • Field splitting shall not be performed on the results of the expansion, with the exception of 

1876 ' @ ' ; see Section 2.5.2 on page 43. 

1877 In addition, a parameter expansion can be modified by using one of the following formats. In 

1878 each case that a value of word is needed (based on the state of parameter, as described below), 

1879 zvord shall be subjected to tilde expansion, parameter expansion, command substitution, and 

1880 arithmetic expansion. If zvord is not needed, it shall not be expanded. The ' } ' character that 

1881 delimits the following parameter expansion modifications shall be determined as described 

1882 previously in this section and in Section 2.2.3 on page 36. (For example, ${foo-bar}xyz} would 

1883 result in the expansion of too followed by the string xyz} if too is set, else the string 

1884 "barxyz}"). 


1885 $| parameter :-zvord } Use Default Values. If parameter is unset or null, the expansion of zvord 

1886 shall be substituted; otherwise, the value of parameter shall be substituted. 


1887 

1888 

1889 

1890 


^{parameter :=zvord] Assign Default Values. If parameter is unset or null, the expansion of 
zvord shall be assigned to parameter. In all cases, the final value of 
parameter shall be substituted. Only variables, not positional parameters 
or special parameters, can be assigned in this way. 


1891 

1892 

1893 

1894 

1895 


^{parameter :?[zvord]} Indicate Error if Null or Unset. If parameter is unset or null, the 
expansion of zvord (or a message indicating it is unset if zvord is omitted) 
shall be written to standard error and the shell exits with a non-zero exit 
status. Otherwise, the value of parameter shall be substituted. An 
interactive shell need not exit. 


1896 ^{parameter :+zvord] Use Alternative Value. If parameter is unset or null, null shall be 

1897 substituted; otherwise, the expansion of zvord shall be substituted. 

1898 In the parameter expansions shown previously, use of the colon in the format results in a test for 

1899 a parameter that is unset or null; omission of the colon results in a test for a parameter that is 

1900 only unset. The following table summarizes the effect of the colon: 


1901 

1902 


parameter 

Set and Not Null 

parameter 

Set But Null 

parameter 

Unset 

1903 

${parameter:-zvord} 

substitute parameter 

substitute zvord 

substitute zvord 

1904 

${parameter-zvord} 

substitute parameter 

substitute null 

substitute zvord 

1905 

${parameter:=zvord } 

substitute parameter 

assign zvord 

assign zvord 

1906 

${parameter=word } 

substitute parameter 

substitute parameter 

assign null 

1907 

${parameter:?zvord} 

substitute parameter 

error, exit 

error, exit 

1908 

${parameter?word } 

substitute parameter 

substitute null 

error, exit 

1909 

${parameter:+zvord } 

substitute zvord 

substitute null 

substitute null 

1910 

${parameter+zvord } 

substitute zvord 

substitute zvord 

substitute null 


1911 In all cases shown with "substitute", the expression is replaced with the value shown. In all 

1912 cases shown with "assign", parameter is assigned that value, which also replaces the expression. 

1913 $| #parameter) String Length. The length in characters of the value of parameter shall be 

1914 substituted. If parameter is ' *' or ' @', the result of the expansion is 

1915 unspecified. 

1916 The following four varieties of parameter expansion provide for substring processing. In each 

1917 case, pattern matching notation (see Section 2.13 on page 92), rather than regular expression 

1918 notation, shall be used to evaluate the patterns. If parameter is ' *' or ' @', the result of the 
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1919 expansion is unspecified. Enclosing the full parameter expansion string in double-quotes shall 

1920 not cause the following four varieties of pattern characters to be quoted, whereas quoting 

1921 characters within the braces shall have this effect. 


1922 

1923 

1924 


$\parameter%word ) Remove Smallest Suffix Pattern. The word, is expanded to produce a 

pattern. The parameter expansion then results in parameter, with the 
smallest portion of the suffix matched by the pattern deleted. 


1925 

1926 

1927 


${parameter%%word ) Remove Largest Suffix Pattern. The word shall be expanded to produce a 
pattern. The parameter expansion then results in parameter, with the 
largest portion of the suffix matched by the pattern deleted. 


1928 

1929 

1930 


${parameter#word} Remove Smallest Prefix Pattern. The zvord shall be expanded to produce 
a pattern. The parameter expansion then results in parameter, with the 
smallest portion of the prefix matched by the pattern deleted. 


1931 

1932 

1933 


${parameter##word] Remove Largest Prefix Pattern. The zvord shall be expanded to produce a 
pattern. The parameter expansion then results in parameter, with the 
largest portion of the prefix matched by the pattern deleted. 


1934 Examples 

1935 ${ parameter :-zvord} 

1936 In this example. Is is executed only if x is null or unset. (The $(/s) command substitution 

1937 notation is explained in Section 2.6.3 on page 54.) 

1938 $ { x : -$ (Is) } 

1939 ${ parameter :-zvord] 

1940 unset X 

1941 echo ${X:=abc} 

1942 abc 

1943 ${ parameter Pzvord) 

1944 unset posix 

1945 echo $ {posix:?} 

1946 sh: posix: parameter null or not set 

1947 ${ parameter \+zvord } 

1948 set a b c 

1949 echo ${3:+posix} 

1950 posix 

1951 ${ ^parameter) 

1952 HOME=/usr/posix 

1953 echo ${#HOME} 

1954 10 

1955 ${parameter%word} 

1956 x=file.c 

1957 echo ${x%.c}.o 

1958 file. o 

1959 ${parameter%%word} 

1960 x=posix/src/std 

1961 echo ${x%%/*} 

1962 posix 
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1963 ${parameter#word } 

1964 x=$HOME/src/cmd 

1965 echo ${x#$HOME} 

1966 /src/cmd 

1967 ${parameter##ivord} 

1968 x=/one/two/three 

1969 echo ${x##*/} 

1970 three 

1971 The double-quoting of patterns is different depending on where the double-quotes are placed: 

1972 The asterisk is a pattern character. 

1973 ${x# The literal asterisk is quoted and not special. 

1974 Rationale 

1975 The rule for finding the closing ' }' in "${...}" is the one used in the KomShell and is 

1976 upwardly compatible with the Bourne shell, which does not determine the closing ' }' until the 

1977 word is expanded. The advantage of this is that incomplete expansions, such as: 

1978 $ { f oo 

1979 can be determined during tokenization, rather than during expansion. 

1980 The string length and substring capabilities were included because of the demonstrated need for 

1981 them, based on their usage in other shells, such as C shell and KomShell. 

1982 Historical versions of the KomShell have not performed tilde expansion on the word part of 

1983 parameter expansion; however, it is more consistent to do so. 

1984 2.6.3 Command Substitution 

1985 Command substitution allows the output of a command to be substituted in place of the 

1986 command name itself. Command substitution shall occur when the command is enclosed as 

1987 follows: 

1988 $ (command) 

1989 or (backquoted version): 

1990 'command' 

1991 The shell shall expand the command substitution by executing command in a subshell 

1992 environment (see Section 2.12 on page 90) and replacing the command substitution (the text of 

1993 command plus the enclosing " $ () " or backquotes) with the standard output of the command, 

1994 removing sequences of one or more <newline> characters at the end of the substitution. 

1995 Embedded <newline> characters before the end of the output shall not be removed; however, 

1996 they may be treated as field delimiters and eliminated during field splitting, depending on the 

1997 value of IFS and quoting that is in effect. 

1998 Within the backquoted style of command substitution, backslash shall retain its literal meaning, 

1999 except when followed by: ' $', ' '', or ' \' (dollar sign, backquote, backslash). The search for I 

2000 the matching backquote shall be satisfied by the first backquote found without a preceding I 

2001 backslash; during this search, if a non-escaped backquote is encountered within a shell 

2002 comment, a here-document, an embedded command substitution of the $( command ) form, or a 

2003 quoted string, undefined results occur. A single-quoted or double-quoted string that begins, but 

2004 does not end, within the " '. . . '" sequence produces undefined results. 
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2005 With the $( command) form, all characters following the open parenthesis to the matching closing 

2006 parenthesis constitute the command. Any valid shell script can be used for command, except: 

2007 • A script consisting solely of redirections produces unspecified results 

2008 • See the restriction on single subshells described below 

2009 The results of command substitution shall not be processed for further tilde expansion, 

2010 parameter expansion, command substitution, or arithmetic expansion. If a command 

2011 substitution occurs inside double-quotes, it shall not be performed on the results of the 

2012 substitution. 


2013 

2014 

2015 

2016 

2017 

2018 
2019 


Command substitution can be nested. To specify nesting within the backquoted version, the I 
application shall precede the inner backquotes with backslashes, for example: I 

\' command \' 

If the command substitution consists of a single subshell, such as: 

$ ( ( command ) ) 

a portable application shall separate the " $ (" and ' (' into two tokens (that is, separate them I 
with white space). This is required to avoid any ambiguities with arithmetic expansion. 


2020 

2021 

2022 


2027 

2028 

2029 

2030 

2031 

2032 

2033 

2034 

2035 

2036 

2037 

2038 

2039 

2040 

2041 

2042 

2043 

2044 


Rationale 

The " $ () " form of command substitution solves a problem of inconsistent behavior when using 
backquotes. For example: 


2023 

Command 

Output 

2024 

echo ' \$x' 

\$x 

2025 

echo 'echo ' \$x' ' 

$x 

2026 

echo $(echo '\$x') 

\$x 


Additionally, the backquoted syntax has historical restrictions on the contents of the embedded 
command. While the newer " $ () " form can process any kind of valid embedded script, the 
backquoted form cannot handle some valid scripts that include backquotes. For example, these 
otherwise valid embedded scripts do not work in the left column, but do work on the right: 


echo ' 
cat «\eof 
a here-doc with ' 

eof 

> 

echo ' 

echo abc # a comment with ' 

> 

echo ' 
echo ' " 


echo $( 
cat «\eof 
a here-doc with ) 
eof 
) 

echo $( 

echo abc # a comment with ) 
) 

echo $( 
echo ')' 

) 


Because of these inconsistent behaviors, the backquoted variety of command substitution is not 
recommended for new applications that nest command substitutions or attempt to embed 
complex scripts. 


2045 


The KomShell feature: 
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2046 If command is of the form <ivord, word is expanded to generate a path name, and the value of 

2047 the command substitution is the contents of this file with any trailing <newline>s deleted. 

2048 was omitted from this volume of IEEE Std. 1003.1-200x because $(cat word) is an appropriate 

2049 substitute. However, to prevent breaking numerous scripts relying on this feature, it is 

2050 unspecified to have a script within " $ () " that has only redirections. 

2051 The requirement to separate " $ (" and ' (' when a single subshell is command-substituted is to 

2052 avoid any ambiguities with arithmetic expansion. 

2053 2.6.4 Arithmetic Expansion 

2054 Arithmetic expansion provides a mechanism for evaluating an arithmetic expression and 

2055 substituting its value. The format for arithmetic expansion shall be as follows: 

2056 $ ( ( expression) ) 

2057 The expression shall be treated as if it were in double-quotes, except that a double-quote inside 

2058 the expression is not treated specially. The shell expands all tokens in the expression for 

2059 parameter expansion, command substitution, and quote removal. 

2060 Next, the shell shall treat this as an arithmetic expression and substitutes the value of the 

2061 expression. The arithmetic expression shall be processed according to the rules of the ISO C 

2062 standard, with the following exceptions: 

2063 • Only integer arithmetic is required. 

2064 • The sizeofi ) operator and the prefix and postfix " + +" and "—" operators are not required. 

2065 • Selection, iteration, and jump statements are not supported. 

2066 As an extension, the shell may recognize arithmetic expressions beyond those listed. If the 

2067 expression is invalid, the expansion fails and the shell shall write a message to standard error 

2068 indicating the failure. 


2069 Examples 

2070 A simple example using arithmetic expansion: 

2071 # repeat a command 100 times 

2072 x=100 

2073 while [ $x —gt 0 ] 

2074 do 

2075 command 

2076 x=$(($x-l)) 

2077 done 


2078 Rationale 

2079 The "(())" form of KornShell arithmetic in early proposals was omitted. The standard 

2080 developers concluded that there was a strong desire for some kind of arithmetic evaluator to 

2081 replace expr, and that relating it to ' $' makes it work well with the standard shell language, and 

2082 it provides access to arithmetic evaluation in places where accessing a utility would be 

2083 inconvenient. 

2084 The syntax and semantics for arithmetic were changed for the ISO/IEC 9945-2:1993 standard. 

2085 The language is essentially a pure arithmetic evaluator of constants and operators (excluding 

2086 assignment) and represents a simple subset of the previous arithmetic language (which was 

2087 derived from the KornShell "(())" construct). The syntax was changed from that of a 
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2088 command denoted by ((expression)) to an expansion denoted by $((expression)). The new form is 

2089 a dollar expansion (' $') that evaluates the expression and substitutes the resulting value. 

2090 Objections to the previous style of arithmetic included that it was too complicated, did not fit in 

2091 well with the use of variables in the shell, and its syntax conflicted with subshells. The 

2092 justification for the new syntax is that the shell is traditionally a macro language, and if a new 

2093 feature is to be added, it should be accomplished by extending the capabilities presented by the 

2094 current model of the shell, rather than by inventing a new one outside the model; adding a new 

2095 dollar expansion was perceived to be the most intuitive and least destructive way to add such a 

2096 new capability. 

2097 In early proposals, a form $[expression] was used. It was functionally equivalent to the "$(())" 

2098 of the current text, but objections were lodged that the 1988 KomShell had already implemented 

2099 "$(())" and there was no compelling reason to invent yet another syntax. Furthermore, the 

2100 " $ [ ] " syntax had a minor incompatibility involving the patterns in case statements. 

2101 The portion of the ISO C standard arithmetic operations selected corresponds to the operations 

2102 historically supported in the KornShell. 

2103 It was concluded that the test command ([) was sufficient for the majority of relational arithmetic 

2104 tests, and that tests involving complicated relational expressions within the shell are rare, yet 

2105 could still be accommodated by testing the value of "$(()) " itself. For example: 

2106 # a complicated relational expression 

2107 while [ $(( ( ($x + $y)/($a * $b) ) < ($foo*$bar) )) —ne 0 ] 

2108 or better yet, the rare script that has many complex relational expressions could define a 

2109 function like this: 

2110 val () { 

2111 return $ ( (!$1) > 

2112 } 

2113 and complicated tests would be less intimidating: 

2114 while val $(( ( ($x + $y)/($a * $b) ) < ($foo*$bar) )) 

2115 do 

2116 # some calculations 

2117 done 

2118 A suggestion that was not adopted was to modify true and false to take an optional argument, 

2119 and true would exit true only if the argument was non-zero, and false would exit false only if the 

2120 argument was non-zero: 

2121 while true $ ( ($x > 5 && $y <= 25) ) 

2122 There is a minor portability concern with the new syntax. The example $((2+2)) could have been 

2123 intended to mean a command substitution of a utility named 2+2 in a subshell. The standard 

2124 developers considered this to be obscure and isolated to some KomShell scripts (because " $ () " 

2125 command substitution existed previously only in the KomShell). The text on command 

2126 substitution requires that the " $ (" and ' (' be separate tokens if this usage is needed. 

2127 An example such as: 

2128 echo $ ( (echo hi) ; (echo there) ) 

2129 should not be misinterpreted by the shell as arithmetic because attempts to balance the 

2130 parentheses pairs would indicate that they are subshells. However, as indicated by the System I 

2131 Interface Definitions volume of IEEE Std. 1003.l-200x. Section 3.115, Control Operator, a I 

2132 conforming application must separate two adjacent parentheses with white space to indicate I 
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2133 nested subshells. 


2134 2.6.5 Field Splitting 

2135 After parameter expansion (Section 2.6.2 on page 51), command substitution (Section 2.6.3 on 

2136 P a g e 54), and arithmetic expansion (Section 2.6.4 on page 56), the shell shall scan the results of 

2137 expansions and substitutions that did not occur in double-quotes for field splitting and multiple 

2138 fields can result. 


2139 The shell shall treat each character of the IFS as a delimiter and uses the delimiters to split the 

2140 results of parameter expansion and command substitution into fields. 


2141 

2142 

2143 

2144 


1. If the value of IFS is a <space>, <tab>, and <newline> character, or if it is unset, any 
sequence of <space>, <tab>, or <newline> characters at the beginning or end of the input 
shall be ignored and any sequence of those characters within the input shall delimit a field. 
For example, the input: 


2145 


<newline><space><tab>foo<tab><tab>bar<space> 


2146 


yields two fields, too and bar. 


2147 

2148 

2149 

2150 

2151 


2. If the value of IFS is null, no field splitting shall be performed. 

3. Otherwise, the following rules shall be applied in sequence. The term “IFS white space" is 
used to mean any sequence (zero or more instances) of white space characters that are in 
the IFS value (for example, if IFS contains <space>/<comma>/<tab>, any sequence of 
<space> and <tab> characters is considered IFS white space). 


2152 


a. IFS white space shall be ignored at the beginning and end of the input. 


2153 

2154 


b. Each occurrence in the input of an IFS character that is not IFS white space, along 
with any adjacent IFS white space, shall delimit a field, as described previously. 


2155 


c. Non-zero-length IFS white space shall delimit a field. 


2156 Rationale 

2157 The operation of field splitting using IFS, as described in early proposals, was based on the way 

2158 the KornShell splits words, but it is incompatible with other common versions of the shell. 

2159 However, each has merit, and so a decision was made to allow both. If the IFS variable is unset 

2160 or is <spacextabxnewline>, the operation is equivalent to the way the System V shell splits 

2161 words. Using characters outside the <spacextabxnewline> set yields the KornShell behavior, 

2162 where each of the non-<spacextabxnewline> characters is significant. This behavior, which 

2163 affords the most flexibility, was taken from the way the original awk handled field splitting. 

2164 Rule (3) can be summarized as a pseudo-ERE: 

2165 ( s*ns* | s+) 

2166 where s is an IFS white space character and n is a character in the IFS that is not white space. 

2167 Any string matching that ERE delimits a field, except that the s+ form does not delimit fields at 

2168 the beginning or the end of a line. For example, if IFS is <space>/ <comma>/ <tab>, the string: 

2169 <space><space>red<space><space>,<space>white<space>blue 

2170 yields the three colors as the delimited fields. 
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2171 2.6.6 Path Name Expansion 

2172 After field splitting, if set -f is not in effect, each field in the resulting command line shall be 

2173 expanded using the algorithm described in Section 2.13 on page 92, qualified by the rules in 

2174 Section 2.13.3 on page 94. 

2175 2.6.7 Quote Removal 

2176 The quote characters: ' \', ' ' ', and ' ' (backslash, single-quote, double-quote) that were 

2177 present in the original word shall be removed unless they have themselves been quoted. 
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2178 2.7 Redirection 

2179 Redirection is used to open and close files for the current shell execution environment (see 

2180 Section 2.12 on page 90) or for any command. Redirection operators can be used with numbers I 

2181 representing file descriptors (see the System Interface Definitions volume of I 

2182 IEEE Std. 1003.1-200x, Section 3.169, File Descriptor) as described below. I 

2183 The overall format used for redirection is: 

2184 [n]redir-op word 

2185 The number n is an optional decimal number designating the file descriptor number; the I 

2186 application shall ensure it is delimited from any preceding text and immediately precede the I 

2187 redirection operator redir-op. If n is quoted, the number shall not be recognized as part of the I 

2188 redirection expression. For example: 

2189 echo \2>a 

2190 writes the character 2 into file a. If any part of redir-op is quoted, no redirection expression is 

2191 recognized. For example: 

2192 echo 2\>a 

2193 writes the characters 2 >a to standard output. The optional number, redirection operator, and 

2194 zvord shall not appear in the arguments provided to the command to be executed (if any). 

2195 Open files are represented by decimal numbers starting with zero. The largest possible value is 

2196 implementation-dependent; however, all implementations support at least 0 to 9, inclusive, for 

2197 use by the application. These numbers are called file descriptors. The values 0, 1, and 2 have 

2198 special meaning and conventional uses and are implied by certain redirection operations; they 

2199 are referred to as standard input, standard output, and standard error, respectively. Programs 

2200 usually take their input from standard input, and write output on standard output. Error 

2201 messages are usually written on standard error. The redirection operators can be preceded by 

2202 one or more digits (with no intervening <blank> characters allowed) to designate the file 

2203 descriptor number. 

2204 If the redirection operator is " << " or the word that follows the redirection operator shall 

2205 be subjected to quote removal; it is unspecified whether any of the other expansions occur. For 

2206 the other redirection operators, the word that follows the redirection operator shall be subjected 

2207 to tilde expansion, parameter expansion, command substitution, arithmetic expansion, and 

2208 quote removal. Path name expansion shall not be performed on the word by a non-interactive 

2209 shell; an interactive shell may perform it, but does do so only when the expansion would result 

2210 in one word. 

2211 If more than one redirection operator is specified with a command, the order of evaluation is 

2212 from beginning to end. 

2213 A failure to open or create a file shall cause a redirection to fail. 
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2214 2.7.1 Redirecting Input 

2215 Input redirection shall cause the file whose name results from the expansion of zvord to be 

2216 opened for reading on the designated file descriptor, or standard input if the file descriptor is not 

2217 specified. 

2218 The general format for redirecting input is: 

2219 [n]<word 

2220 where the optional n represents the file descriptor number. If the number is omitted, the 

2221 redirection shall refer to standard input (file descriptor 0). 

2222 2.7.2 Redirecting Output 

2223 The two general formats for redirecting output are: 

2224 [ n ] > word 

2225 [ n ] > | word 

2226 where the optional n represents the file descriptor number. If the number is omitted, the 

2227 redirection shall refer to standard output (file descriptor 1). 

2228 Output redirection using the ' >' format fails if the noclobber option is set (see the description of 

2229 set -C) and the file named by the expansion of zvord exists and is a regular file. Otherwise, 

2230 redirection using the ' >' or "> | " formats shall cause the file whose name results from the 

2231 expansion of zvord to be created and opened for output on the designated file descriptor, or 

2232 standard output if none is specified. If the file does not exist, it shall be created; otherwise, it 

2233 shall be truncated to be an empty file after being opened. 

2234 2.7.3 Appending Redirected Output 

2235 Appended output redirection shall cause the file whose name results from the expansion of 

2236 word to be opened for output on the designated file descriptor. The file is opened as if the open () 

2237 function as defined in the System Interfaces volume of IEEE Std. 1003.1-200x was called with the 

2238 0_APPEND flag. If the file does not exist, it shall be created. 

2239 The general format for appending redirected output is as follows: 

2240 [n]>>word 

2241 where the optional n represents the file descriptor number. If the number is omitted, the 

2242 redirection refers to standard output (file descriptor 1). 

2243 2.7.4 Here-Document 

2244 The redirection operators "<<" and both allow redirection of lines contained in a shell 

2245 input file, known as a here-document , to the input of a command. 

2246 The here-document shall be treated as a single word that begins after the next <newline> 

2247 character and continues until there is a line containing only the delimiter, with no trailing 

2248 <blank> characters. Then the next here-document starts, if there is one. The format is as follows: 

2249 [n]<<word 

2250 here-document 

2251 delimiter 

2252 where the optional n represents the file descriptor number. If the number is omitted, the here- 

2253 document refers to standard output (file descriptor 0). 
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2254 If any character in word is quoted, the delimiter shall be formed by performing quote removal on 

2255 word, and the here-document lines are not expanded. Otherwise, the delimiter shall be the zvord 

2256 itself. 

2257 If no characters in zvord are quoted, all lines of the here-document shall be expanded for 

2258 parameter expansion, command substitution, and arithmetic expansion. In this case, the 

2259 backslash in the input behaves as the backslash inside double-quotes (see Section 2.2.3 on page 

2260 36). However, the double-quote character (' ) ' shall not be treated specially within a here- 

2261 document, except when the double-quote appears within or " $ {}". 

2262 If the redirection symbol is all leading tab characters shall be stripped from input lines 

2263 and the line containing the trailing delimiter. If more than one "<<" or operator is 

2264 specified on a line, the here-document associated with the first operator shall be supplied first by 

2265 the application and shall be read first by the shell. 

2266 Examples 

2267 An example of a here-document follows: 

2268 cat <<eofl; cat <<eof2 

2269 Hi, 

2270 eof 1 

2271 Helene. 

2272 eof 2 

2273 2.7.5 Duplicating an Input File Descriptor 

2274 The redirection operator: 

2275 [n] <&word 

2276 is used to duplicate one input file descriptor from another, or to close one. If zvord evaluates to 

2277 one or more digits, the file descriptor denoted by n, or standard input if n is not specified, shall 

2278 be made to be a copy of the file descriptor denoted by zvord ; if the digits in zvord do not represent 

2279 a file descriptor already open for input, a redirection error shall result; see Section 2.8.1 on page 

2280 65. If zvord evaluates to file descriptor n, or standard input if n is not specified, shall be 

2281 closed. If zvord evaluates to something else, the behavior is unspecified. 

2282 2.7.6 Duplicating an Output File Descriptor 

2283 The redirection operator: 

2284 [n] > & word 

2285 is used to duplicate one output file descriptor from another, or to close one. If zvord evaluates to 

2286 one or more digits, the file descriptor denoted by n, or standard output if n is not specified, shall 

2287 be made to be a copy of the file descriptor denoted by zvord ; if the digits in zvord do not represent 

2288 a file descriptor already open for output, a redirection error shall result; see Section 2.8.1 on page 

2289 65. If zvord evaluates to ' , file descriptor n, or standard output if n is not specified, is closed. If 

2290 zvord evaluates to something else, the behavior is unspecified. 
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2291 2.7.7 Open File Descriptors for Reading and Writing 

2292 The redirection operator: 

2293 [n]Oword 

2294 shall cause the file whose name is the expansion of ivord to be opened for both reading and 

2295 writing on the file descriptor denoted by n, or standard input if n is not specified. If the file does 

2296 not exist, it shall be created. 

2297 Rationale 

2298 In the System Interfaces volume of IEEE Std. 1003.1-200x, file descriptors are integers in the 

2299 range 0-({OPEN_MAX}-1). The file descriptors discussed in Section 2.7 on page 60 are that same 

2300 set of small integers. 

2301 Having multi-digit file descriptor numbers for I/O redirection can cause some obscure 

2302 compatibility problems. Specifically, scripts that depend on an example command: 

2303 echo 22>/dev/null 

2304 echoing 2 to standard error or 22 to standard output are no longer portable. However, the file 

2305 descriptor number still must be delimited from the preceding text. For example: 

2306 cat file2>foo 

2307 writes the contents of file2, not the contents of file. 

2308 The " > | " format of output redirection was adopted from the KomShell. Along with the 

2309 noclobber option, set -C, it provides a safety feature to prevent inadvertent overwriting of 

2310 existing files. (See the RATIONALE for pathchk on page 732 for why this step was taken.) The 

2311 restriction on regular files is historical practice. 

2312 The System V shell and the KomShell have differed historically on path name expansion of word ; 

2313 the former never performed it, the latter only when the result was a single field (file). As a 

2314 compromise, it was decided that the KomShell functionality was useful, but only as a shorthand 

2315 device for interactive users. No reasonable shell script would be written with a command such 

2316 as: 

2317 cat foo > a* 

2318 Thus, shell scripts are prohibited from doing it, while interactive users can select the shell with 

2319 which they are most comfortable. 

2320 The construct 2>&1 is often used to redirect standard error to the same file as standard output. 

2321 Since the redirections take place beginning to end, the order of redirections is significant. For 

2322 example: 

2323 Is > foo 2>& 1 

2324 directs both standard output and standard error to file foo. However: 

2325 Is 2>& 1 > foo 

2326 only directs standard output to file foo because standard error was duplicated as standard 

2327 output before standard output was directed to file foo. 

2328 The " <> " operator could be useful in writing an application that worked with several terminals, 

2329 and occasionally wanted to start up a shell. That shell would in turn be unable to run 

2330 applications that run from an ordinary controlling terminal unless it could make use of "<>" 

2331 redirection. The specific example is a historical version of the pager more, which reads from 
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2332 standard error to get its commands, so standard input and standard output are both available 

2333 for their usual usage. There is no way of saying the following in the shell without 

2334 cat food I more — >/dev/tty03 2<>/dev/tty03 

2335 Another example of " <> " is one that opens /dev/tty on file descriptor 3 for reading and writing: 

2336 exec 3<> /dev/tty 

2337 An example of creating a lock file for a critical code region: 

2338 set -C 

2339 until 2> /dev/null > lockfile 

2340 do sleep 30 

2341 done 

2342 set +C 

2343 perforin critical function 

2344 rm lockfile 

2345 Since /dev/null is not a regular file, no error is generated by redirecting to it in noclobber mode. 

2346 Tilde expansion is not performed on a here-document because the data is treated as if it were 

2347 enclosed in double quotes. 
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2348 2.8 Exit Status and Errors 


2349 2.8.1 Consequences of Shell Errors 


2350 

2351 

2352 

2353 

2354 

2355 

2356 

2357 

2358 

2359 

2360 


For a non-interactive shell, an error condition encountered by a special built-in (see Section 2.14 
on page 96) or other type of utility shall cause the shell to write a diagnostic message to standard 
error and exit as shown in the following table: 


Error 

Special Built-In 

Other Utilities 

Shell language syntax error 

Exits 

Exits 


Utility syntax error (option or operand error) 

Exits 

Does not 

exit 

Redirection error 

Exits 

Does not 

exit 

Variable assignment error 

Exits 

Does not 

exit 

Expansion error 

Exits 

Exits 


Command not found 

N/A 

May exit 


Dot script not found 

Exits 

N/A 



2361 An expansion error is one that occurs when the shell expansions defined in Section 2.6 on page 

2362 49 are carried out (for example, "${x!y}", because ' !' is not a valid operator); an 

2363 implementation may treat these as syntax errors if it is able to detect them during tokenization, 

2364 rather than during expansion. 


2365 If any of the errors shown as "shall exit" or "(may) exit" occur in a subshell, the subshell shall 

2366 (or may exit) with a non-zero status, but the script containing the subshell shall not exit because 

2367 of the error. 


2368 In all of the cases shown in the table, an interactive shell shall write a diagnostic message to 

2369 standard error without exiting. 


2370 2.8.2 Exit Status for Commands 

2371 Each command has an exit status that can influence the behavior of other shell commands. The 

2372 exit status of commands that are not utilities is documented in this section. The exit status of the 

2373 standard utilities is documented in their respective sections. 

2374 If a command is not found, the exit status shall be 127. If the command name is found, but it is 

2375 not an executable utility, the exit status shall be 126. Applications that invoke utilities without 

2376 using the shell should use these exit status values to report similar errors. 

2377 If a command fails during word expansion or redirection, its exit status shall be greater than 

2378 zero. 

2379 Internally, for purposes of deciding whether a command exits with a non-zero exit status, the 

2380 shell shall recognize the entire status value retrieved for the command by the equivalent of the 

2381 zvait() function WEXITSTATUS macro (as defined in the System Interfaces volume of 

2382 IEEE Std. 1003.1-200x). When reporting the exit status with the special parameter ' ?', the shell 

2383 shall report the full eight bits of exit status available. The exit status of a command that 

2384 terminated because it received a signal shall be reported as greater than 128. 
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2385 Rationale 

2386 There is a historical difference in sh and ksh non-interactive error behavior. When a command 

2387 named in a script is not found, some implementations of sh exit immediately, but ksh continues 

2388 with the next command. Thus, this volume of IEEE Std. 1003.1-200x says that the shell "may" 

2389 exit in this case. This puts a small burden on the programmer, who has to test for successful 

2390 completion following a command if it is important that the next command not be executed if the 

2391 previous command was not found. If it is important for the command to have been found, it was 

2392 probably also important for it to complete successfully. The test for successful completion would 

2393 not need to change. 

2394 Historically, shells have returned an exit status of 128+n, where n represents the signal number. 

2395 Since signal numbers are not standardized, there is no portable way to determine which signal 

2396 caused the termination. Also, it is possible for a command to exit with a status in the same range 

2397 of numbers that the shell would use to report that the command was terminated by a signal. 

2398 Implementations are encouraged to choose exit values greater than 256 to indicate programs 

2399 that terminate by a signal so that the exit status cannot be confused with an exit status generated 

2400 by a normal termination. 

2401 Historical shells make the distinction between "utility not found" and "utility found but cannot 

2402 execute" in their error messages. By specifying two seldomly used exit status values for these 

2403 cases, 127 and 126 respectively, this gives an application the opportunity to make use of this 

2404 distinction without having to parse an error message that would probably change from locale to 

2405 locale. The command, env, nohup, and xargs utilities in this volume of IEEE Std. 1003.1-200x have 

2406 also been specified to use this convention. 

2407 When a command fails during word expansion or redirection, most historical implementations 

2408 exit with a status of 1. However, there was some sentiment that this value should probably be 

2409 much higher so that an application could distinguish this case from the more normal exit status 

2410 values. Thus, the language "greater than zero" was selected to allow either method to be 

2411 implemented. 
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2412 2.9 Shell Commands 

2413 This section describes the basic structure of shell commands. The following command 

2414 descriptions each describe a format of the command that is only used to aid the reader in 

2415 recognizing the command type, and does not formally represent the syntax. Each description 

2416 discusses the semantics of the command; for a formal definition of the command language, 

2417 consult Section 2.10 on page 82. 

2418 A command is one of the following: 

2419 • Simple command (see Section 2.9.1) 

2420 • Pipeline (see Section 2.9.2 on page 72) 

2421 • List or compound-list (see Section 2.9.3 on page 73) 

2422 • Compound command (see Section 2.9.4 on page 75) 

2423 • Function definition (see Section 2.9.5 on page 79) 

2424 Unless otherwise stated, the exit status of a command is that of the last simple command 

2425 executed by the command. There is no limit on the size of any shell command other than that 

2426 imposed by the underlying system (memory constraints, {ARG_MAX}, and so on). 

2427 Rationale 

2428 A description of an "empty command" was removed from an early proposal because it is only 

2429 relevant in the cases of sh -c " ", system(" "), or an empty shell-script file (such as the 

2430 implementation of true on some historical systems). Since it is no longer mentioned in this 

2431 volume of IEEE Std. 1003.1-200x, it falls into the silently unspecified category of behavior where 

2432 implementations can continue to operate as they have historically, but conforming applications 

2433 do not construct empty commands. (However, note that sh does explicitly state an exit status for 

2434 an empty string or file.) In an interactive session or a script with other commands, extra 

2435 <newline>s or semicolons, such as; 

2436 $ false 

2437 $ 

2438 $ echo $? 

2439 1 

2440 would not qualify as the empty command described here because they would be consumed by 

2441 other parts of the grammar. 

2442 2.9.1 Simple Commands 

2443 A simple command is a sequence of optional variable assignments and redirections, in any 

2444 sequence, optionally followed by words and redirections, terminated by a control operator. 

2445 When a given simple command is required to be executed (that is, when any conditional 

2446 construct such as an AND-OR list or a case statement has not bypassed the simple command), 

2447 the following expansions, assignments, and redirections are all performed from the beginning of 

2448 the command text to the end: 

2449 1. The words that are recognized as variable assignments or redirections according to Section 

2450 2.10.2 on page 82 are saved for processing in steps 3 and 4. 

2451 2. The words that are not variable assignments or redirections shall be expanded. If any fields 

2452 remain following their expansion, the first field shall be considered the command name 

2453 and remaining fields are the arguments for the command. 
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2454 3. Redirections shall be performed as described in Section 2.7 on page 60. 

2455 4. Each variable assignment shall be expanded for tilde expansion, parameter expansion, 

2456 command substitution, arithmetic expansion, and quote removal prior to assigning the 

2457 value. 

2458 In the preceding list, the order of steps 3 and 4 may be reversed for the processing of special 

2459 built-in utilities; see Section 2.14 on page 96. 

2460 If no command name results, variable assignments shall affect the current execution 

2461 environment. Otherwise, the variable assignments shall be exported for the execution 

2462 environment of the command and shall not affect the current execution environment (except for 

2463 special built-ins). If any of the variable assignments attempt to assign a value to a read-only 

2464 variable, a variable assignment error occurs. See Section 2.8.1 on page 65 for the consequences of 

2465 these errors. 

2466 If there is no command name, any redirections shall be performed in a subshell environment; it 

2467 is unspecified whether this subshell environment is the same one as that used for a command 

2468 substitution within the command. (To affect the current execution environment, see the exec on 

2469 P a g e 107 special built-in.) If any of the redirections performed in the current shell execution 

2470 environment fail, the command shall immediately fail with an exit status greater than zero, and 

2471 the shell shall write an error message indicating the failure. See Section 2.8.1 on page 65 for the 

2472 consequences of these failures on interactive and non-interactive shells. 

2473 If there is a command name, execution shall continue as described in Section 2.9.1.1 on page 69. 

2474 If there is no command name, but the command contained a command substitution, the 

2475 command shall complete with the exit status of the last command substitution performed. 

2476 Otherwise, the command shall complete with a zero exit status. 

2477 Rationale 

2478 The enumerated list is used only when the command is actually going to be executed. For 

2479 example, in: 

2480 true I | $foo * 

2481 no expansions are performed. 

2482 The following example illustrates both how a variable assignment without a command name 

2483 affects the current execution environment, and how an assignment with a command name only 

2484 affects the execution environment of the command: 

2485 $ x=red 

2486 $ echo $x 

2487 red 

2488 $ export x 

2489 $ sh —c 'echo $x' 

2490 red 

2491 $ x=blue sh —c 'echo $x' 

2492 blue 

2493 $ echo $x 

2494 red 

2495 This next example illustrates that redirections without a command name are still performed: 
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2496 

2497 

2498 

2499 

2500 

2501 

2502 

2503 

2504 

2505 

2506 

2507 

2508 

2509 

2510 

2511 

2512 

2513 

2514 

2515 

2516 

2517 

2518 

2519 

2520 

2521 

2522 

2523 

2524 

2525 


$ Is foo 

Is: foo: no such file or directory 

$ > foo 
$ Is foo 

foo 

A command without a command name, but one that includes a command substitution, has an 
exit status of the last command substitution that the shell performed. For example: 


if 

then 

fi 


x=$( command) 


An example of redirections without a command name being performed in a subshell shows that 
the here-document does not disrupt the standard input of the while loop: 


IFS=: 
while 
do 


read a b 
echo $a 
<<—eof 
Hello 
eof 

done </etc/passwd 

Some examples of commands without command names in AND-OR lists: 

> foo | | { 

echo "error: foo cannot be created" >&2 
exit 1 


# set saved if /vmunix.save exists 
test —f /vmunix.save && saved=l 

Command substitution and redirections without command names both occur in subshells, but 
they are not necessarily the same ones. For example, in: 

exec 3> file 

var=$(echo foo >&3) 3>&1 


2526 


it is unspecified whether foo is echoed to the file or to standard output. 


2527 2.9.1.1 Command Search and Execution 


2528 If a simple command results in a command name and an optional list of arguments, the 

2529 following actions shall be performed: 


2530 1. If the command name does not contain any slashes, the first successful step in the 

2531 following sequence shall occur: 


2532 

2533 


a. If the command name matches the name of a special built-in utility, that special 
built-in utility shall be invoked. 


2534 

2535 

2536 

2537 

2538 


b. If the command name matches the name of a function known to this shell, the 
function shall be invoked as described in Section 2.9.5 on page 79. If the 
implementation has provided a standard utility in the form of a function, it shall not 
be recognized at this point. It shall be invoked in conjunction with the path search in 
step Id. 
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2539 c. If the command name matches the name of a utility listed in the following table, that 

2540 utility shall be invoked. 


2541 

alias 

false 

jobs 

true 

2542 

bg 

fc 

kill 

umask 

2543 

cd 

fg 

new grp 

unalias 

2544 

command 

getopts 

read 

wait 


2545 d. Otherwise, the command is searched for using the PATH environment variable as I 

2546 described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

2547 Chapter 8, Environment Variables: I 

2548 i. If the search is successful: 


2549 a. If the system has implemented the utility as a regular built-in or as a shell 

2550 function, it shall be invoked at this point in the path search. 


2551 

2552 

2553 

2554 

2555 

2556 


b. Otherwise, the shell executes the utility in a separate utility environment 
(see Section 2.12 on page 90) with actions equivalent to calling the 
execve () function as defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x with the path argument set to the path name 
resulting from the search, arg 0 set to the command name, and the 
remaining arguments set to the operands, if any. 


2557 

2558 

2559 

2560 

2561 

2562 

2563 


If the execve () function fails due to an error equivalent to the [ENOEXEC] 
error defined in the System Interfaces volume of IEEE Std. 1003.1-200x, 
the shell shall execute a command equivalent to having a shell invoked 
with the command name as its first operand, along with any remaining 
arguments passed along. If the executable file is not a text file, the shell 
may bypass this command execution, write an error message, and return 
an exit status of 126. 


2564 

2565 

2566 

2567 

2568 

2569 


Once a utility has been searched for and found (either as a result of this specific I 

search or as part of an unspecified shell start-up activity), an implementation I 
may remember its location and need not search for the utility again unless the 
PATH variable has been the subject of an assignment. If the remembered 
location fails for a subsequent invocation, the shell shall repeat the search to 
find the new location for the utility, if any. 


2570 ii. If the search is unsuccessful, the command shall fail with an exit status of 127 

2571 and the shell shall write an error message. 


2572 2. If the command name contains at least one slash, the shell shall execute the utility in a 

2573 separate utility environment with actions equivalent to calling the execve () function 

2574 defined in the System Interfaces volume of IEEE Std. 1003.1-200x with the path and argO 

2575 arguments set to the command name, and the remaining arguments set to the operands, if 

2576 any. 


2577 If the execve () function fails due to an error equivalent to the [ENOEXEC] error, the shell 

2578 shall execute a command equivalent to having a shell invoked with the command name as 

2579 its first operand, along with any remaining arguments passed along. If the executable file is 

2580 not a text file, the shell may bypass this command execution, write an error message, and 

2581 return an exit status of 126. 
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2582 Rationale 

2583 This description requires that the shell can execute shell scripts directly, even if the underlying 

2584 system does not support the common " # !" interpreter convention. That is, if file foo contains 

2585 shell commands and is executable, the following executes foo: 

2586 ./foo 

2587 The command search shown here does not match all historical implementations. A more typical 

2588 sequence has been: 

2589 • Any built-in (special or regular) 

2590 • Functions 

2591 • Path search for executable files 

2592 But there are problems with this sequence. Since the programmer has no idea in advance which 

2593 utilities might have been built into the shell, a function cannot be used to override portably a 

2594 utility of the same name. (For example, a function named cd cannot be written for many 

2595 historical systems.) Furthermore, the PATH variable is partially ineffective in this case, and only 

2596 a path name with a slash can be used to ensure a specific executable file is invoked. 

2597 After the execve( ) failure described, the shell normally executes the file as a shell script. Some 

2598 implementations, however, attempt to detect whether the file is actually a script and not an 

2599 executable from some other architecture. The method used by the KomShell is allowed by the 

2600 text that indicates non-text files may be bypassed. 

2601 The sequence selected for this volume of IEEE Std. 1003.1-200x acknowledges that special built- 

2602 ins cannot be overridden, but gives the programmer full control over which versions of other 

2603 utilities are executed. It provides a means of suppressing function lookup (via the command 

2604 utility) for the user 7 s own functions and ensures that any regular built-ins or functions provided 

2605 by the implementation are under the control of the path search. The mechanisms for associating 

2606 built-ins or functions with executable files in the path are not specified by this volume of 

2607 IEEE Std. 1003.1-200x, but the wording requires that if either is implemented, the application is 

2608 not able to distinguish a function or built-in from an executable (other than in terms of 

2609 performance, presumably). The implementation ensures that all effects specified by this volume 

2610 of IEEE Std. 1003.1-200x resulting from the invocation of the regular built-in or function 

2611 (interaction with the environment, variables, traps, and so on) are identical to those resulting 

2612 from the invocation of an executable file. 

2613 Examples 

2614 Consider three versions of the Is utility: 

2615 1. The application includes a shell function named Is. 

2616 2. The user writes a utility named Is and puts it in /fred/bin. 

2617 3. The example implementation provides Is as a regular shell built-in that is invoked (either 

2618 by the shell or directly by exec) when the path search reaches the directory /posix/bin. 

2619 If PATH=/posix/bin, various invocations yield different versions of Is: 
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2620 


2621 

Invocation 

Version of Is 

2622 

Is (from within application script) 

(1) function 

2623 

command Is (from within application script) 

(3) built-in 

2624 

Is (from within makefile called by application) 

(3) built-in 

2625 

system("ls") 

(3) built-in 

2626 

PATH="/hed/bin:$PATH" Is 

(2) user's version 


2627 2.9.2 Pipelines 

2628 A pipeline is a sequence of one or more commands separated by the control operator ' | . The 

2629 standard output of all but the last command shall be connected to the standard input of the next 

2630 command. 

2631 The format for a pipeline is: 

2632 [ ! ] commandl [ \ command2 . . . ] 

2633 The standard output of commandl shall be connected to the standard input of commandl . The 

2634 standard input, standard output, or both of a command shall be considered to be assigned by the 

2635 pipeline before any redirection specified by redirection operators that are part of the command 

2636 (see Section 2.7 on page 60). 

2637 If the pipeline is not in the background (see Section 2.9.3.1 on page 74), the shell shall wait for the 

2638 last command specified in the pipeline to complete, and may also wait for all commands to 

2639 complete. 


2640 Exit Status 


2641 If the reserved word ! does not precede the pipeline, the exit status shall be the exit status of the 

2642 last command specified in the pipeline. Otherwise, the exit status shall be the logical NOT of the 

2643 exit status of the last command. That is, if the last command returns zero, the exit status shall be 

2644 1; if the last command returns greater than zero, the exit status shall be zero. 


2645 Rationale 

2646 Because pipeline assignment of standard input or standard output or both takes place before 

2647 redirection, it can be modified by redirection. For example: 

2648 $ commandl 2>&1 | command2 

2649 sends both the standard output and standard error of commandl to the standard input of 

2650 command2. 


2651 The reserved word ! allows more flexible testing using AND and OR lists. 

2652 It was suggested that it would be better to return a non-zero value if any command in the 

2653 pipeline terminates with non-zero status (perhaps the bitwise-inclusive OR of all return values). 

2654 However, the choice of the last-specified command semantics are historical practice and would 

2655 cause applications to break if changed. An example of historical behavior: 


2656 

2657 

2658 

2659 

2660 
2661 


$ sleep 5 | (exit 4) 
$ echo $? 

4 

$ (exit 4) | sleep 5 

$ echo $? 

0 
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2662 2.9.3 Lists 


2663 An AND-OR list is a sequence of one or more pipelines separated by the operators " & &" and 

2664 "| | ". 


2665 A list is a sequence of one or more AND-OR lists separated by the operators ' ;' and ' &' and 

2666 optionally terminated by or <newline>. 


2667 The operators " & &" and " | | " shall have equal precedence and are evaluated from beginning to 

2668 end. For example, both of the following commands write solely bar to standard output: 


2669 false && echo foo | | echo bar 

2670 true | | echo foo && echo bar 


2671 A ' ;' or <newline> character terminator shall cause the preceding AND-OR list to be executed 

2672 sequentially; an ' &' shall cause asynchronous execution of the preceding AND-OR list. 


2673 The term compound-list is derived from the grammar in Section 2.10 on page 82; it is equivalent to 

2674 a sequence of lists, separated by <newline> characters, that can be preceded or followed by an 

2675 arbitrary number of <newline> characters. 


2676 Examples 

2677 The following is an example that illustrates <newline> characters in compound-lists: 


2678 

2679 

2680 
2681 
2682 

2683 

2684 


while 

# a couple of <newline>s 

# a list 

date && who || Is; cat file 

# a couple of <newline>s 

# another list 

wc file > output & true 


2685 

2686 

2687 

2688 
2689 


# 2 lists 
Is 

cat file 


done 


2690 Rationale 


2691 

2692 

2693 

2694 

2695 

2696 


The equal precedence of "&&" and " | | " is historical practice. The standard developers 
evaluated the model used more frequently in high-level programming languages, such as C, to 
allow the shell logical operators to be used for complex expressions in an unambiguous way, but 
they could not allow historical scripts to break in the subtle way unequal precedence might 
cause. Some arguments were posed concerning the " { }" or " () " groupings that are required 
historically. There are some disadvantages to these groupings: 


2697 • The " () " can be expensive, as they spawn other processes on some systems. This 

2698 performance concern is primarily an implementation issue. 


2699 

2700 

2701 

2702 

2703 

2704 


• The " { }" braces are not operators (they are reserved words) and require a trailing space after 
each ' {', and a semicolon before each ' }'. Most programmers (and certainly interactive 
users) have avoided braces as grouping constructs because of the problematic syntax 
required. Braces were not changed to operators because that would generate compatibility 
issues even greater than the precedence question; braces appear outside the context of a 
keyword in many shell scripts. 
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2705 2.9.3.1 Asynchronous Lists 

2706 If a command is terminated by the control operator ampersand (' &'), the shell shall execute the 

2707 command asynchronously in a subshell. This means that the shell shall not wait for the 

2708 command to finish before executing the next command. 

2709 The format for running a command in the background is: 

2710 commandl & [command2 & ... ] 

2711 The standard input for an asynchronous list, before any explicit redirections are performed, shall 

2712 be considered to be assigned to a file that has the same properties as /dev/null. If it is an 

2713 interactive shell, this need not happen. In all cases, explicit redirection of standard input shall 

2714 override this activity. 

2715 When an element of an asynchronous list (the portion of the list ended by an ampersand, such as 

2716 commandl , above) is started by the shell, the process ID of the last command in the asynchronous 

2717 list element shall become known in the current shell execution environment; see Section 2.12 on 

2718 page 90. This process ID shall remain known until: 

2719 1. The command terminates and the application waits for the process ID. 

2720 2. Another asynchronous list invoked before " $!" (corresponding to the previous 

2721 asynchronous list) is expanded in the current execution environment. 

2722 The implementation need not retain more than the |CHILD_MAX} most recent entries in its list 

2723 of known process IDs in the current shell execution environment. 

2724 Exit Status 

2725 The exit status of an asynchronous list shall be zero. 

2726 Rationale 

2727 The grammar treats a construct such as: 

2728 foo & bar & bam & 

2729 as one "asynchronous list", but since the status of each element is tracked by the shell, the term 

2730 "element of an asynchronous list" was introduced to identify just one of the foo, bar, or bam 

2731 portions of the overall list. 

2732 Unless the implementation has an internal limit, such as |CHILD_MAX}, on the retained process 

2733 IDs, it would require unbounded memory for the following example: 

2734 while true 

2735 do foo & echo $! 

2736 done 

2737 The treatment of the signals SIGINT and SIGQUIT with asynchronous lists is described in 

2738 Section 2.11 on page 89. 

2739 Since the connection of the input to the equivalent of /dev/null is considered to occur before 

2740 redirections, the following script would produce no output: 

2741 exec < /etc/passwd 

2742 cat <&0 & 

2743 wait 
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2744 2.9.3.2 Sequential Lists 

2745 Commands that are separated by a semicolon (' ;') shall be executed sequentially. 

2746 The format for executing commands sequentially shall be: 

2747 commandl [; command2 ] . . . 

2748 Each command shall be expanded and executed in the order specified. 

2749 Exit Status 

2750 The exit status of a sequential list shall be the exit status of the last command in the list. 

2751 2.9.3.3 AND Lists 

2752 The control operator " & &" denotes an AND list. The format shall be: 

2753 commandl [ && command2 ] . . . 

2754 First commandl shall be executed. If its exit status is zero, command2 shall be executed, and so on, 

2755 until a command has a non-zero exit status or there are no more commands left to execute. The 

2756 commands are expanded only if they are executed. 

2757 Exit Status 

2758 The exit status of an AND list shall be the exit status of the last command that is executed in the 

2759 list. 

2760 2.9.3A OR Lists 

2761 The control operator " | | " denotes an OR List. The format shall be: 

2762 commandl [ | | command2 ] . . . 

2763 First, commandl shall be executed. If its exit status is non-zero, commandl shall be executed, and 

2764 so on, until a command has a zero exit status or there are no more commands left to execute. 

2765 Exit Status 

2766 The exit status of an OR list shall be the exit status of the last command that is executed in the 

2767 list. 

2768 2.9.4 Compound Commands 

2769 The shell has several programming constructs that are compound commands, which provide 

2770 control flow for commands. Each of these compound commands has a reserved word or control 

2771 operator at the beginning, and a corresponding terminator reserved word or operator at the end. 

2772 In addition, each can be followed by redirections on the same line as the terminator. Each 

2773 redirection shall apply to all the commands within the compound command that do not 

2774 explicitly override that redirection. 

2775 2. 9.4.1 Grouping Commands 

2776 The format for grouping commands is as follows: 

Till ( compound-list ) Execute compound-list in a subshell environment; see Section 2.12 on page 

2778 90. Variable assignments and built-in commands that affect the 

2779 environment shall not remain in effect after the list finishes. 
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2780 j compound-list ;} Execute compound-list in the current process environment. The semicolon 

2781 shown here is an example of a control operator delimiting the } reserved 

2782 word. Other delimiters are possible, as shown in Section 2.10 on page 82; 

2783 a <newline> character is frequently used. 

2784 Exit Status 

2785 The exit status of a grouping command shall be the exit status of list. 

2786 Rationale 

2787 The semicolon shown { compound-list ;} is an example of a control operator delimiting the } 

2788 reserved word. Other delimiters are possible, as shown in Section 2.10 on page 82; <newline> is 

2789 frequently used. 

2790 A proposal was made to use the <do-done> construct in all cases where command grouping in 

2791 the current process environment is performed, identifying it as a construct for the grouping 

2792 commands, as well as for shell functions. This was not included because the shell already has a 

2793 grouping construct for this purpose (" {}"), and changing it would have been counter- 

2794 productive. 

2795 2.9.4.2 For Loop 

2796 The for loop executes a sequence of commands for each member in a list of items. The for loop 

2797 requires that the reserved words do and done be used to delimit the sequence of commands. 

2798 The format for the for loop is as follows: 

2799 for name [ in word ... ] 

2800 do 

2801 compound-list 

2802 done 

2803 First, the list of words following in shall be expanded to generate a list of items. Then, the 

2804 variable name shall be set to each item, in turn, and the compound-list executed each time. If no 

2805 items result from the expansion, the compound-list shall not be executed. Omitting: 

2806 in word... 

2807 is equivalent to: 

2808 in "$@" 

2809 Exit Status 

2810 The exit status of a for command shall be the exit status of the last command that executes. If 

2811 there are no items, the exit status shall be zero. 
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2812 Rationale 

2813 The format is shown with generous usage of <newline>s. See the grammar in Section 2.10 on 

2814 page 82 for a precise description of where <newline>s and semicolons can be interchanged. 

2815 Some historical implementations support ' {' and ' }' as substitutes for do and done. The 

2816 standard developers chose to omit them, even as an obsolescent feature. (Note that these 

2817 substitutes were only for the for command; the while and until commands could not use them 

2818 historically because they are followed by compound-lists that may contain "{•••}" grouping 

2819 commands themselves.) 

2820 The reserved word pair do ... done was selected rather than do ... od (which would have 

2821 matched the spirit of if ... fi and case ... esac) because od is already the name of a standard 

2822 utility. 

2823 2 .9.4.3 Case Conditional Construct 

2824 The conditional construct case shall execute the compound-list corresponding to the first one of 

2825 several patterns (see Section 2.13 on page 92) that is matched by the string resulting from the tilde 

2826 expansion, parameter expansion, command substitution, arithmetic expansion, and quote 

2827 removal of the given word. The reserved word in shall denote the beginning of the patterns to be 

2828 matched. Multiple patterns with the same compound-list shall be delimited by the ' \ ' symbol. 

2829 The control operator ' ) ' terminates a list of patterns corresponding to a given action. The 

2830 compound-list for each list of patterns, with the possible exception of the last, shall be terminated I 

2831 with ";; ". The case construct terminates with the reserved word esac (case reversed). I 

2832 The format for the case construct is as follows: 

2833 case word in 

2834 [( ]patternl ) compound-list; ; 

2835 [[(] pattern [ | pattern ] ... ) compound-list; ; ] ... 

2836 [[(]pattern[ \ pattern ] ... ) compound-list] 

2837 esac 

2838 The "; ; " is optional for the last compound-list . 

2839 In order from the beginning to the end of the case statement, each pattern that labels a 

2840 compound-list shall be subjected to tilde expansion, parameter expansion, command substitution, 

2841 and arithmetic expansion, and the result of these expansions shall be compared against the 

2842 expansion of word, according to the rules described in Section 2.13 on page 92 (which also 

2843 describes the effect of quoting parts of the pattern). After the first match, no more patterns shall 

2844 be expanded, and the compound-list shall be executed. The order of expansion and comparison of 

2845 multiple patterns that label a compound-list statement is unspecified. 

2846 Exit Status 

2847 The exit status of case shall be zero if no patterns are matched. Otherwise, the exit status shall be 

2848 the exit status of the last command executed in the compound-list. 
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2849 Rationale 

2850 An optional left parenthesis before pattern was added to allow numerous historical KomShell 

2851 scripts to conform. At one time, using the leading parenthesis was required if the case statement 

2852 was to be embedded within a " $ () " command substitution; this is no longer the case with the 

2853 POSIX shell. Nevertheless, many historical scripts use the left parenthesis, if only because it 

2854 makes matching-parenthesis searching easier in vi and other editors. This is a relatively simple 

2855 implementation change that is upward compatible for all scripts. 

2856 Consideration was given to requiring break inside the compound-list to prevent falling through to 

2857 the next pattern action list. This was rejected as being nonexisting practice. An interesting 

2858 undocumented feature of the KomShell is that using "; &" instead of "; ; " as a terminator 

2859 causes the exact opposite behavior—the flow of control continues with the next compound-list. 

2860 The pattern ' *', given as the last pattern in a case construct, is equivalent to the default case in 

2861 a C-language switch statement. 

2862 The grammar shows that reserved words can be used as patterns, even if one is the first word on 

2863 a line. Obviously, the reserved word esac cannot be used in this manner. 

2864 2.9.4.4 If Conditional Construct 

2865 The if command shall execute a compound-list and use its exit status to determine whether to 

2866 execute another compound-list. 

2867 The format for the if construct is as follows: 

2868 if compound-list 

2869 then 

2870 compound-list 

2871 [elif compound-list 

2872 then 

2873 compound-list ] . . . 

2874 [else 

2875 compound-list] 

2876 The if compound-list shall be executed; if its exit status is zero, the then compound-list shall be 

2877 executed and the command shall complete. Otherwise, each elif compound-list shall be executed, 

2878 in turn, and if its exit status is zero, the then compound-list shall be executed and the command 

2879 shall complete. Otherwise, the else compound-list shall be executed. 

2880 Exit Status 

2881 The exit status of the if command shall be the exit status of the then or else compound-list that 

2882 was executed, or zero, if none was executed. 

2883 Rationale 

2884 The precise format for the command syntax is described in Section 2.10 on page 82. 

2885 2 .9.4.5 While Loop 

2886 The while loop shall continuously execute one compound-list as long as another compound-list has 

2887 a zero exit status. 

2888 The format of the while loop is as follows: 
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2889 while compound-list-1 

2890 do 

2891 compound-list-2 

2892 done 

2893 The compound-list-1 shall be executed, and if it has a non-zero exit status, the while command 

2894 shall complete. Otherwise, the compound-list-2 shall be executed, and the process shall repeat. 

2895 Exit Status 

2896 The exit status of the while loop shall be the exit status of the last compound-list-2 executed, or 

2897 zero if none was executed. 

2898 Rationale 

2899 The precise format for the command syntax is described in Section 2.10 on page 82. 

2900 2.9.4.6 Until Loop 

2901 The until loop shall continuously execute one compound-list as long as another compound-list has 

2902 a non-zero exit status. 

2903 The format of the until loop is as follows: 

2904 until compound-list-1 

2905 do 

2906 compound-list-2 

2907 done 

2908 The compound-list-1 shall be executed, and if it has a zero exit status, the until command 

2909 completes. Otherwise, the compound-list-2 shall be executed, and the process repeats. 

2910 Exit Status 

2911 The exit status of the until loop shall be the exit status of the last compound-list-2 executed, or 

2912 zero if none was executed. 

2913 Rationale 

2914 The precise format for the command syntax is described in Section 2.10 on page 82. 

2915 2.9.5 Function Definition Command 

2916 A function is a user-defined name that is used as a simple command to call a compound 

2917 command with new positional parameters. A function is defined with a function definition 

2918 command. 

2919 The format of a function definition command is as follows: 

2920 fname () compound-command[io-redirect ...] 

2921 The function is named fname ; the application shall ensure that it is a name (see the System I 

2922 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.234, Name). An implementation I 

2923 may allow other characters in a function name as an extension. The implementation shall I 

2924 maintain separate name spaces for functions and variables. I 

2925 The argument compound-command represents a compound command, as described in Section 

2926 2.9.4 on page 75. 
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2927 When the function is declared, none of the expansions in Section 2.6 on page 49 shall be 

2928 performed on the text in compound-command or io-redirect ; all expansions shall be performed as 

2929 normal each time the function is called. Similarly, the optional io-redirect redirections and any 

2930 variable assignments within compound-command shall be performed during the execution of the 

2931 function itself, not the function definition. See Section 2.8.1 on page 65 for the consequences of 

2932 failures of these operations on interactive and non-interactive shells. 

2933 When a function is executed, it shall have the syntax-error and variable-assignment properties 

2934 described for special built-in utilities in the enumerated list at the beginning of Section 2.14 on 

2935 page 96. 

2936 The compound-command shall be executed whenever the function name is specified as the name 

2937 of a simple command (see Section 2.9.1.1 on page 69). The operands to the command 

2938 temporarily shall become the positional parameters during the execution of the compound- 

2939 command ; the special parameter ' #' also shall be changed to reflect the number of operands. The 

2940 special parameter 0 shall be unchanged. When the function completes, the values of the 

2941 positional parameters and the special parameter ' #' shall be restored to the values they had 

2942 before the function was executed. If the special built-in return is executed in the compound- 

2943 command, the function completes and execution shall resume with the next command after the 

2944 function call. 

2945 Exit Status 

2946 The exit status of a function definition shall be zero if the function was declared successfully; 

2947 otherwise, it shall be greater than zero. The exit status of a function invocation shall be the exit 

2948 status of the last command executed by the function. 

2949 Rationale 

2950 The description of functions in an early proposal was based on the notion that functions should 

2951 behave like miniature shell scripts; that is, except for sharing variables, most elements of an 

2952 execution environment should behave as if they were a new execution environment, and 

2953 changes to these should be local to the function. For example, traps and options should be reset 

2954 on entry to the function, and any changes to them do not affect the traps or options of the caller. 

2955 There were numerous objections to this basic idea, and the opponents asserted that functions 

2956 were intended to be a convenient mechanism for grouping common commands that were to be 

2957 executed in the current execution environment, similar to the execution of the dot special built- 

2958 in. 

2959 It was also pointed out that the functions described in that early proposal did not provide a local 

2960 scope for everything a new shell script would, such as the current working directory, or umask, 

2961 but instead provided a local scope for only a few select properties. The basic argument was that 

2962 if a local scope is needed for the execution environment, the mechanism already existed: the 

2963 application can put the commands in a new shell script and call that script. All historical shells 

2964 that implemented functions, other than the KomShell, have implemented functions that operate 

2965 in the current execution environment. Because of this, traps and options have a global scope 

2966 within a shell script. Local variables within a function were considered and included in another 

2967 early proposal (controlled by the special built-in local), but were removed because they do not fit 

2968 the simple model developed for functions and because there was some opposition to adding yet 

2969 another new special built-in that was not part of historical practice. Implementations should 

2970 reserve the identifier local (as well as typeset, as used in the KomShell) in case this local variable 

2971 mechanism is adopted in a future version of this volume of IEEE Std. 1003.1-200x. 

2972 A separate issue from the execution environment of a function is the availability of that function 

2973 to child shells. A few objectors maintained that just as a variable can be shared with child shells 
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2974 by exporting it, so should a function—and so this capability has been added to this volume of 

2975 IEEE Std. 1003.1-200x. In early proposals, the export command therefore had a -f flag for 

2976 exporting functions. Functions that were exported were to be put into the environment as 

2977 name( )=value pairs, and upon invocation, the shell would scan the environment for these and 

2978 automatically define these functions. This facility was strongly opposed and was omitted. Some 

2979 of the arguments against exportable functions were as follows: 

2980 • There was little historical practice. The Ninth Edition shell provided them, but there was 

2981 controversy over how well it worked. 

2982 • There are numerous security problems associated with functions appearing in the 

2983 environment of a user and overriding standard utilities or the utilities owned by the 

2984 application. 

2985 • There was controversy over requiring make to import functions, where it has historically used 

2986 an exec function for many of its command line executions. 

2987 • Functions can be big and the environment is of a limited size. (The counter-argument was 

2988 that functions are no different than variables in terms of size: there can be big ones, and there 

2989 can be small ones—and just as one does not export huge variables, one does not export huge 

2990 functions. However, this might not apply to the average shell-function writer, who typically 

2991 writes much larger functions than variables.) 

2992 As far as can be determined, the functions in this volume of IEEE Std. 1003.1-200x match those in 

2993 System V. Earlier versions of the KomShell had two methods of defining functions: 

2994 function fname { compound-list } 

2995 and: 

2996 fname () { compound-list } 

2997 The latter used the same definition as this volume of IEEE Std. 1003.1-200x, but differed in 

2998 semantics, as described previously. The current edition of the KomShell aligns the latter syntax 

2999 with this volume of IEEE Std. 1003.1-200x and keeps the former as is. 

3000 The name space for functions is limited to that of a name because of historical practice. 

3001 Complications in defining the syntactic rules for the function definition command and in dealing 

3002 with known extensions such as the " @ () " usage in the KomShell prevented the name space 

3003 from being widened to a word. Using functions to support synonyms such as the " ! ! " and ' %' 

3004 usage in the C shell is thus disallowed to portable applications, but acceptable as an extension. 

3005 For interactive users, the aliasing facilities in this volume of IEEE Std. 1003.1-200x should be 

3006 adequate for this purpose. It is recognized that the name space for utilities in the file system is 

3007 wider than that currently supported for functions, if the portable file name character set 

3008 guidelines are ignored, but it did not seem useful to mandate extensions in systems for so little 

3009 benefit to portable applications. 

3010 The " () " in the function definition command consists of two operators. Therefore, intermixing 

3011 <blank>s with th e fname, ' ( ' , and ' ) ' is allowed, but unnecessary. 

3012 An example of how a function definition can be used wherever a simple command is allowed: 

3013 # If variable i is equal to "yes", 

3014 # define function foo to be is —1 

3015 # 

3016 [ "$i" = yes ] && foo() { 

3017 is -1 

3018 } 
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3019 2.10 Shell Grammar 

3020 The following grammar defines the Shell Command Language. This formal syntax shall take 

3021 precedence over the preceding text syntax description. 

3022 2.10.1 Shell Grammar Lexical Conventions 

3023 The input language to the shell must be first recognized at the character level. The resulting 

3024 tokens shall be classified by their immediate context according to the following rules (applied in 

3025 order). These rules are used to determine what a "token” is that is subject to parsing at the 

3026 token level. The rules for token recognition in Section 2.3 on page 39 shall apply. 

3027 1. A <newline> character shall be returned as the token identifier NEWLINE. 

3028 2. If the token is an operator, the token identifier for that operator shall result. 

3029 3. If the string consists solely of digits and the delimiter character is one of ' <’ or ' , the 

3030 token identifier IO_NUMBER shall be returned. 

3031 4. Otherwise, the token identifier TOKEN results. 

3032 Further distinction on TOKEN is context-dependent. It may be that the same TOKEN yields 

3033 WORD, a NAME, an ASSIGNMENT, or one of the reserved words below, dependent upon the 

3034 context. Some of the productions in the grammar below are annotated with a rule number from 

3035 the following list. When a TOKEN is seen where one of those annotated productions could be 

3036 used to reduce the symbol, the applicable rule shall be applied to convert the token identifier 

3037 type of the TOKEN to a token identifier acceptable at that point in the grammar. The reduction 

3038 shall then proceed based upon the token identifier type yielded by the rule applied. When more 

3039 than one rule applies, the highest numbered rule shall apply (which in turn may refer to another 

3040 rule). (Note that except in rule 7, the presence of an ' =' in the token has no effect.) 

3041 The WORD tokens shall have the word expansion rules applied to them immediately before the 

3042 associated command is executed, not at the time the command is parsed. 


3043 2.10.2 Shell Grammar Rules 

3044 1. [Command Name] 


When the TOKEN is exactly a reserved word, the token identifier for that reserved word 
shall result. Otherwise, the token WORD shall be returned. Also, if the parser is in any 
state where only a reserved word could be the next correct token, proceed as above. This 
rule applies rather narrowly: when a compound list is terminated by some clear delimiter 
(such as the closing fi of an inner if_clause) then it would apply; where the compound list 
might continue (as in after a ' ;'), rule 7a (and consequently the first sentence of this rule) 
would apply. In many instances the two conditions are identical, but this part of this rule 
does not give license to treating a WORD as a reserved word unless it is in a place where a 
reserved word shall appear. 

Note: Because at this point quote marks are retained in the token, quoted strings 

cannot be recognized as reserved words. This rule also implies that reserved 
words are not recognized except in certain positions in the input, such as after a 
<newline> character or semicolon; the grammar presumes that if the reserved 
word is intended, it is properly delimited by the user, and does not attempt to 
reflect that requirement directly. Also note that line joining is done before 
tokenization, as described in Section 2.2.1 on page 36, so escaped <newline>s 
are already removed at this point. 
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3062 Rule 1 is not directly referenced in the grammar, but is referred to by other rules, or applies 

3063 globally. 


3064 


2. [Redirection to or from file name] 


3065 

3066 

3067 


The expansions specified in Section 2.7 on page 60 shall occur. As specified there, exactly 
one field can result (or the result is unspecified), and there are additional requirements on 
path name expansion. 


3068 


3. [Redirection from here-document] 


3069 

3070 


Quote removal shall be applied to the word to determine the delimiter that is used to find 
the end of the here-document that begins after the next <newline> character. 


3071 


4. [Case statement termination] 


3072 When the TOKEN is exactly the reserved word esac, the token identifier for esac shall 

3073 result. Otherwise, the token WORD shall be returned. 


3074 


5. [NAME in for] 


3075 

3076 

3077 


When the TOKEN meets the requirements for a name (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.234, Name), the token identifier NAME shall I 
result. Otherwise, the token WORD shall be returned. 


3078 


6. [Third word of for and case] 


3079 

3080 

3081 

3082 


When the TOKEN is exactly the reserved word in, the token identifier for in shall result. 
Otherwise, the token WORD shall be returned. (As indicated in the grammar, a linebreak 
precedes the token in. If <newline> characters are present at the indicated location, it is 
the token after them that is treated in this fashion.) 


3083 


7. [Assignment preceding command name] 


3084 


a. [When the first word] 


3085 

3086 


If the TOKEN does not contain the character ' = ', rule 1 is applied. Otherwise, 7b 
shall be applied. 


3087 


b. [Not the first word] 


3088 


If the TOKEN contains the equal sign character: 


3089 


— If it begins with ' = ', the token WORD shall be returned. 


3090 

3091 

3092 

3093 


— If all the characters preceding ' =' form a valid name (see the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 3.234, Name), the token I 
ASSIGNMENT_WORD shall be returned. (Quoted characters cannot participate 
in forming a valid name.) 


3094 

3095 


— Otherwise, it is unspecified whether it is ASSIGNMENT_WORD or WORD that 
is returned. 


3096 Assignment to the NAME shall occur as specified in Section 2.9.1 on page 67. 

3097 8. [NAME in function] 


3098 

3099 

3100 


When the TOKEN is exactly a reserved word, the token identifier for that reserved word 
shall result. Otherwise, when the TOKEN meets the requirements for a name, the token 
identifier NAME shall result. Otherwise, rule 7 applies. 


3101 


9. [Body of function] 
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3102 Word expansion and assignment shall never occur, even when required by the rules above, 

3103 when this rule is being parsed. Each TOKEN that might either be expanded or have 

3104 assignment applied to it shall instead be returned as a single WORD consisting only of 

3105 characters that are exactly the token described in Section 2.3 on page 39. 

3106 /* - 

3107 The grammar symbols 

3108 - */ 

3109 %token WORD 

3110 %token AS SI GNMENT_WORD 

3111 %token NAME 

3112 %token NEWLINE 

3113 %token IO_NUMBER 

3114 /* The following are the operators mentioned above. */ 

3115 %token AND_IF OR_IF DSEMI 

3116 /* ' &&' ' | I' ' ; ; ' */ 

3117 %token DLESS DGREAT LESSAND GREATAND LESSGREAT DLESSDASH 

3118 /* '«' '»' '<&' '>&' 'O' '«-' */ 

3119 %token CLOBBER 

3120 / * ' > I' * / 

3121 /* The following are the reserved words. */ 

3122 %token If Then Else Elif Fi Do Done 

3123 /* 'if' 'then' 'else' 'elif' 'fi' 'do' 'done' */ 

3124 %token Case Esac While Until For 

3125 /* 'case' 'esac' 'while' 'until' 'for' */ 

3126 /* These are reserved words, not operator tokens, and are 

3127 recognized when reserved words are recognized. */ 

3128 %token Lbrace Rbrace Bang 

3129 / * '{' '}' '!' * / 

3130 %token In 

3131 /* 'in' */ 

3132 / * - 

3133 The Grammar 

3134 - * / 

3135 %start complete_command 

3136 "6 "6 

3137 complete_command : list separator 

3138 I list 

3139 ; 

3140 list : list separator_op and_or 

3141 | and_or 

3142 ; 

3143 and_or : pipeline 

3144 | and_or AND_IF linebreak pipeline 

3145 I and_or OR_IF linebreak pipeline 

3146 ; 
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3147 

pipeline 


pipe_sequence 


3148 


1 

Bang pipe_sequence 


3149 


r 



3150 

pipe_sequence 


command 


3151 


1 

pipe_sequence '|' linebreak command 


3152 


r 



3153 

command 


simple_command 


3154 


1 

compound_command 


3155 


1 

compound_command redirect_list 


3156 


1 

function_definition 


3157 


r 



3158 

compound_command 


brace_group 


3159 


1 

subshell 


3160 


1 

for_clause 


3161 


1 

case_clause 


3162 


1 

if_clause 


3163 


1 

while_clause 


3164 


1 

until_clause 


3165 


r 



3166 

subshell 


' (' compound_list ')' 


3167 


r 



3168 

compound_list 


term 


3169 


1 

newline_list term 


3170 


1 

term separator 


3171 


1 

newline_list term separator 


3172 


r 



3173 

term 


term separator and_or 


3174 


1 

and_or 


3175 


r 



3176 

for_clause 


For name linebreak 

do_group 

3177 


1 

For name linebreak in wordlist sequential_sep 

do_group 

3178 


r 



3179 

name 


NAME /* Apply rule 5 */ 


3180 


r 



3181 

in 


In /* Apply rule 6 */ 


3182 


r 



3183 

wordlist 


wordlist WORD 


3184 


1 

WORD 


3185 


r 



3186 

case_clause 


Case WORD linebreak in linebreak case_list Esac 

3187 


1 

Case WORD linebreak in linebreak case_list_ns 

Esac 

3188 


1 

Case WORD linebreak in linebreak Esac 


3189 


r 



3190 

case_list_ns 


case_list case_item_ns 


3191 


1 

case_item_ns 


3192 


r 



3193 

case_list 


case_list case_item 


3194 


1 

case_item 


3195 


r 



3196 

case_item_ns 


pattern ' )' linebreak linebreak 


3197 


1 

pattern ')' compound_list linebreak 


3198 


1 

' (' pattern ')' linebreak linebreak 
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3199 

3200 

3201 

3202 

3203 

3204 

3205 

3206 

3207 

3208 

3209 

3210 

3211 

3212 

3213 

3214 

3215 

3216 

3217 

3218 

3219 

3220 

3221 

3222 

3223 

3224 

3225 

3226 

3227 

3228 

3229 

3230 

3231 

3232 

3233 

3234 

3235 

3236 

3237 

3238 

3239 

3240 

3241 

3242 

3243 

3244 

3245 

3246 

3247 

3248 

3249 

3250 


I '(' pattern ')' compound_list linebreak 


case item 


: pattern ')' linebreak DSEMI linebreak 
I pattern ')' compound_list linebreak 
I '(' pattern ')' linebreak linebreak 
I '(' pattern ')' compound_list linebreak 


pattern 


if clause 


else_part 


: WORD 

I pattern ' \' WORD 


/* Apply rule 4 */ 

/* Do not apply rule (4) */ 


: If compound_list Then compound_list else_part Fi 
| If compound_list Then compound_list Fi 

r 

: Elif compound_list Then else_part 
I Else compound_list 


while_clause 
until clause 


: While compound_list do_group 

r 

: Until compound_list do_group 

r 

function_definition : fname '(' ')' linebreak function_body 

function_body 


: compound_command /* Apply rule 9 */ 

I compound_command redirect_list /* Apply rule 9 */ 


fname 

brace_group 

do_group 

simple_command 


NAME 

Lbrace compound_list Rbrace 

Do compound_list Done 

cmd_prefix cmd_word cmd_suffix 
| cmd_prefix cmd_word 
| cmd_prefix 
| cmd_name cmd_suffix 
| cmd_name 


/* Apply rule 8 */ 


cmd_name 
cmd_word 
cmd_prefix 


WORD 

WORD 


/* Apply rule 7a */ 
/* Apply rule 7b */ 


cmd suffix 


redirect list 


: io_redirect 

| cmd_prefix io_redirect 
| AS SIGNMENT_WORD 

| cmd_prefix ASSIGNMENT_WORD 

r 

: io_redirect 

| cmd_suffix io_redirect 
| WORD 

| cmd_suffix WORD 

r 

: io redirect 
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3251 


| redirect_list io_redirect 

3252 


r 

3253 

io_redirect 

: io_file 

3254 


| IO_NUMBER io_file 

3255 


I io_here 

3256 


| IO_NUMBER io_here 

3257 


r 

3258 

io_f ile 

: ' <’ filename 

3259 


| LESSAND filename 

3260 


| ' >' filename 

3261 


| GREATAND filename 

3262 


| DGREAT filename 

3263 


I LESSGREAT filename 

3264 


| CLOBBER filename 

3265 


r 

3266 

filename 

: WORD /* Apply rule 2 */ 

3267 


r 

3268 

io_here 

: DLESS here_end 

3269 


| DLESSDASH here_end 

3270 


r 

3271 

here_end 

: WORD /* Apply rule 3 */ 

3272 


r 

3273 

newline_list 

: NEWLINE 

3274 


| newline_list NEWLINE 

3275 


r 

3276 

linebreak 

: newline_list 

3277 


| /* empty */ 

3278 


r 

3279 

separator_op 

: ' 

3280 


1 

3281 


r 

3282 

separator 

: separator_op linebreak 

3283 


| newline_list 

3284 


r 

3285 

sequential_sep : ';' linebreak 

3286 


| newline_list 

3287 


r 

3288 

Rationale 


3289 

There are several subtle aspects of this grammar where conventional usage implies rules about 

3290 

the grammar that in fact are not true. 

3291 

For compoundjist, only the forms that end in a separator allow a reserved word to be recognized. 

3292 

so usually only a 

separator can be used where a compound list precedes a reserved word (such as 

3293 

Then, Else, Do and Rbrace). Explicitly requiring a separator would disallow such valid (if rare) 

3294 

statements as: 


3295 

if (false) 

then (echo x) else (echo y) fi 

3296 

See the Note under special grammar rule 1. 

3297 

Concerning the third sentence of rule (1) ("Also, if the parser 
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3298 • This sentence applies rather narrowly: when a compound list is terminated by some clear 

3299 delimiter (such as the closing fi of an inner if_clause) then it would apply; where the 

3300 compound list might continue (as in after a ' ; '), rule (7a) (and consequently the first 

3301 sentence of rule (1)) would apply. In many instances the two conditions are identical, but this 

3302 part of rule (1) does not give license to treating a WORD as a reserved word unless it is in a I 

3303 place where a reserved word has to appear. I 

3304 • The statement is equivalent to requiring that when the LR(1) lookahead set contains exactly 

3305 one reserved word, it must be recognized if it is present. (Here "LRfl)" refers to the 

3306 theoretical concepts, not to any real parser generator.) 

3307 For example, in the construct below, and when the parser is at the point marked with ' *', 

3308 the only next legal token is then (this follows directly from the grammar rules): 

3309 if if. . .fi then ... fi 

3310 

3311 At that point, the then must be recognized as a reserved word. 

3312 (Depending on the parser generator actually used, "extra" reserved words may be in some 

3313 lookahead sets. It does not really matter if they are recognized, or even if any possible 

3314 reserved word is recognized in that state, because if it is recognized and is not in the 

3315 (theoretical) LR(1) lookahead set, an error is ultimately detected. In the example above, if 

3316 some other reserved word (for example, while) is also recognized, an error occurs later. 

3317 This is approximately equivalent to saying that reserved words are recognized after other 

3318 reserved words (because it is after a reserved word that this condition occurs), but avoids the 

3319 "except for ..." list that would be required for case, for, and so on. (Reserved words are of 

3320 course recognized anywhere a simplejcommand can appear, as well. Other rules take care of 

3321 the special cases of non-recognition, such as rule (4) for case statements.) 

3322 Note that the body of here-documents are handled by token recognition (see Section 2.3 on page 

3323 39) and do not appear in the grammar directly. (However, the here-document I/O redirection 

3324 operator is handled as part of the grammar.) 

3325 The start symbol of the grammar (complete_command) represents either input from the 

3326 command line or a shell script. It is repeatedly applied by the interpreter to its input and 

3327 represents a single "chunk" of that input as seen by the interpreter. 
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3328 2.11 Signals and Error Handling 

3329 When a command is in an asynchronous list, the shell shall prevent SIGQUIT and SIGINT 

3330 signals from the keyboard from interrupting the command. Otherwise, signals shall have the 

3331 values inherited by the shell from its parent (see also the trap on page 127 special built-in). 

3332 When a signal for which a trap has been set is received while the shell is waiting for the 

3333 completion of a utility executing a foreground command, the trap associated with that signal 

3334 shall not be executed until after the foreground command has completed. When the shell is 

3335 waiting, by means of the wait utility, for asynchronous commands to complete, the reception of a 

3336 signal for which a trap has been set shall cause the wait utility to return immediately with an exit 

3337 status >128, immediately after which the trap associated with that signal shall be taken. 

3338 If multiple signals are pending for the shell for which there are associated trap actions, the order 

3339 of execution of trap actions is unspecified. 
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3340 2.12 Shell Execution Environment 


3341 

3342 

3343 

3344 

3345 

3346 

3347 

3348 

3349 

3350 

3351 

3352 

3353 


A shell execution environment consists of the following: 

• Open files inherited upon invocation of the shell, plus open files controlled by exec 

• Working directory as set by cd 

• File creation mask set by umask 

• Current traps set by trap 

• Shell parameters that are set by variable assignment (see the set on page 117 special built-in) 
or from the System Interfaces volume of IEEE Std. 1003.1-200x environment inherited by the 
shell when it begins (see the export on page 111 special built-in) 

• Shell functions; see Section 2.9.5 on page 79 

• Options turned on at invocation or by set 

• Process IDs of the last commands in asynchronous lists known to this shell environment; see 
Section 2.9.3.1 on page 74 

• Shell aliases; see Section 2.3.1 on page 40 


3354 Utilities other than the special built-ins (see Section 2.14 on page 96) shall be invoked in a 

3355 separate environment that consists of the following. The initial value of these objects shall be the 

3356 same as that for the parent shell, except as noted below. 


3357 

3358 


• Open files inherited on invocation of the shell, open files controlled by the exec special built- 
in plus any modifications, and additions specified by any redirections to the utility 


3359 


• Current working directory 


3360 


• File creation mask 


3361 

3362 

3363 

3364 


• If the utility is a shell script, traps caught by the shell shall be set to the default values and 
traps ignored by the shell shall be set to be ignored by the utility; if the utility is not a shell 
script, the trap actions (default or ignore) shall be mapped into the appropriate signal 
handling actions for the utility 


3365 

3366 

3367 


• Variables with the export attribute, along with those explicitly exported for the duration of the 
command, shall be passed to the utility as System Interfaces volume of IEEE Std. 1003.1-200x 
environment variables 


3368 The environment of the shell process shall not be changed by the utility unless explicitly 

3369 specified by the utility description (for example, cd and umask). 


3370 

3371 

3372 

3373 

3374 

3375 

3376 

3377 


A subshell environment shall be created as a duplicate of the shell environment, except that 
signal traps set by that shell environment shall be set to the default values. Changes made to the 
subshell environment shall not affect the shell environment. Command substitution, commands 
that are grouped with parentheses, and asynchronous lists shall be executed in a subshell 
environment. Additionally, each command of a multi-command pipeline is in a subshell 
environment; as an extension, however, any or all commands in a pipeline may be executed in 
the current environment. All other commands shall be executed in the current shell 
environment. 
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3378 Rationale 

3379 Some systems have implemented the last stage of a pipeline in the current environment so that 

3380 commands such as: 

3381 command I read foo 

3382 set variable foo in the current environment. This extension is allowed, but not required; 

3383 therefore, a shell programmer should consider a pipeline to be in a subshell environment, but 

3384 not depend on it. 

3385 In early proposals, the description of execution environment failed to mention that each 

3386 command in a multiple command pipeline could be in a subshell execution environment. For 

3387 compatibility with some historical shells, the wording was phrased to allow an implementation 

3388 to place any or all commands of a pipeline in the current environment. However, this means that 

3389 a POSIX application must assume each command is in a subshell environment, but not depend 

3390 on it. 

3391 The wording about shell scripts is meant to convey the fact that describing "trap actions" can 

3392 only be understood in the context of the shell command language. Outside of this context, such 

3393 as in a C-language program, signals are the operative condition, not traps. 
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3394 2.13 Pattern Matching Notation 

3395 The pattern matching notation described in this section is used to specify patterns for matching 

3396 strings in the shell. Historically, pattern matching notation is related to, but slightly different 

3397 from, the regular expression notation described in the System Interface Definitions volume of I 

3398 IEEE Std. 1003.1-200x, Chapter 9, Regular Expressions. For this reason, the description of the I 

3399 rules for this pattern matching notation are based on the description of regular expression I 

3400 notation, modified to include backslash escape processing. I 

3401 Rationale 

3402 Pattern matching is a simpler concept and has a simpler syntax than REs, as the former is 

3403 generally used for the manipulation of file names, which are relatively simple collections of 

3404 characters, while the latter is generally used to manipulate arbitrary text strings of potentially 

3405 greater complexity. However, some of the basic concepts are the same, so this section points 

3406 liberally to the detailed descriptions in the System Interface Definitions volume of I 

3407 IEEE Std. 1003.1-200x, Chapter 9, Regular Expressions. I 

3408 2.13.1 Patterns Matching a Single Character 

3409 The following patterns matching a single character match a single character: ordinary characters, 

3410 special pattern characters, and pattern bracket expressions. The pattern bracket expression also shall 

3411 match a single collating element. A backslash character shall escape the following character. The I 

3412 escaping backslash shall be discarded. I 

3413 An ordinary character is a pattern that shall match itself. It can be any character in the supported 

3414 character set except for NUL, those special shell characters in Section 2.2 on page 36 that require 

3415 quoting, and the following three special pattern characters. Matching shall be based on the bit 

3416 pattern used for encoding the character, not on the graphic representation of the character. If any 

3417 character (ordinary, shell special, or pattern special) is quoted, that pattern shall match the 

3418 character itself. The shell special characters always require quoting. 

3419 When unquoted and outside a bracket expression, the following three characters shall have 

3420 special meaning in the specification of patterns: 

3421 ? A question-mark is a pattern that shall match any character. 

3422 * An asterisk is a pattern that shall match multiple characters, as described in Section 2.13.2 

3423 on page 93. 

3424 [ The open bracket shall introduce a pattern bracket expression. 

3425 The description of basic regular expression bracket expressions in the System Interface I 

3426 Definitions volume of IEEE Std. 1003.1-200x, Section 9.3.5, RE Bracket Expression shall also I 

3427 apply to the pattern bracket expression, except that the exclamation-mark character (' !') shall I 

3428 replace the circumflex character (' ~') in its role in a non-matching list in the regular expression 

3429 notation. A bracket expression starting with an unquoted circumflex character produces 

3430 unspecified results. 

3431 When pattern matching is used where shell quote removal is not performed (such as in the 

3432 argument to the find name primary when find is being called using one of the exec functions as 

3433 defined in the System Interfaces volume of IEEE Std. 1003.1-200x, or in the pattern argument to 

3434 the fnmatch () function), special characters can be escaped to remove their special meaning by 

3435 preceding them with a backslash character. This escaping backslash is discarded. The sequence 

3436 " \ \" represents one literal backslash. All of the requirements and effects of quoting on ordinary, 

3437 shell special, and special pattern characters shall apply to escaping in this context. 
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3438 Rationale 


3439 

3440 

3441 

3442 

3443 

3444 

3445 


Both quoting and escaping are described here because pattern matching must work in three 
separate circumstances: 

1. Calling directly upon the shell, such as in path name expansion or in a case statement. All 
of the following match the string or file abc: 

abc "abc" a"b"c a\bc a[b]c a["b"]c a[\b]c a["\b"]c a?c a*c 

The following do not: 

"a?c" a\*c a\[b]c 


3446 

3447 

3448 

3449 


2. Calling a utility or function without going through a shell, as described for find and the 
fnmatchi ) function defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 

3. Calling utilities such as find, cpio, tar, or pax through the shell command line. In this case, 
shell quote removal is performed before the utility sees the argument. For example, in: 


3450 


find /bin —name "e\c[\h]o" —print 


3451 

3452 

3453 

3454 

3455 


after quote removal, the backslashes are presented to find and it treats them as escape 
characters. Both precede ordinary characters, so the c and h represent themselves and echo 
would be found on many historical systems (that have it in /bin). To find a file name that 
contained shell special characters or pattern characters, both quoting and escaping are 
required, such as: 


3456 


pax —r ... "*a\ (\? " 


3457 to extract a file name ending with " a (? ". 

3458 Conforming applications are required to quote or escape the shell special characters (sometimes 

3459 called metacharacters). If used without this protection, syntax errors can result or 

3460 implementation extensions can be triggered. For example, the KomShell supports a series of 

3461 extensions based on parentheses in patterns. 

3462 The restriction on a circumflex in a bracket expression is to allow implementations that support 

3463 pattern matching using the circumflex as the negation character in addition to the exclamation- 

3464 mark. A portable application must use something like " [ \ ~ ! ] " to match either character. 


3465 2.13.2 Patterns Matching Multiple Characters 


3466 The following rules are used to construct patterns matching multiple characters from patterns 

3467 matching a single character: 


3468 

3469 

3470 

3471 


1. The asterisk (' *') is a pattern that shall match any string, including the null string. 

2. The concatenation of patterns matching a single character is a valid pattern that shall match 
the concatenation of the single characters or collating elements matched by each of the 
concatenated patterns. 


3472 

3473 

3474 

3475 


3. The concatenation of one or more patterns matching a single character with one or more 
asterisks is a valid pattern. In such patterns, each asterisk shall match a string of zero or 
more characters, matching the greatest possible number of characters that still allows the 
remainder of the pattern to match the string. 
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3476 Rationale 

3477 Since each asterisk matches zero or more occurrences, the patterns "a*b" and "a**b" have 

3478 identical functionality. 


3479 

3480 

3481 

3482 

3483 


Examples 

a [be] 
a*d 
a*d* 
*a*d 


Matches the strings "ab" and "ac". 

Matches the strings "ad", "abd",and "abed", but not the string "abc". 
Matches the strings "ad", "abed", "abedef", "aaaad",and "adddd". 
Matches the strings "ad", "abed", "efabed", "aaaad",and "adddd". 


3484 2.13.3 Patterns Used for File Name Expansion 


3485 

3486 

3487 


The rules described so far in Section 2.13.1 on page 92 and Section 2.13.2 on page 93 are qualified 
by the following rules that apply when pattern matching notation is used for file name 
expansion: 


3488 

3489 

3490 

3491 

3492 MAN 

3493 

3494 

3495 

3496 


1. The application shall ensure that the slash character in a path name is explicitly matched 
by using one or more slashes in the pattern; it cannot be matched by the asterisk or 
question-mark special characters or by a bracket expression. Slashes in the pattern are 
identified before bracket expressions; thus, a slash cannot be included in a pattern bracket 
expression used for file name expansion. If a slash character is found following an 
unescaped open square bracket character before a corresponding closing square bracket is 
found, the open bracket is treated as an ordinary character. For example, the pattern 
"a [b/c] d" does not match such path names as abd or a/d. It only matches a path name 
of literally a[b/c]d. 


3497 

3498 

3499 


2. If a file name begins with a period (' .'), the application shall ensure that the period is I 
explicitly matched by using a period as the first character of the pattern or immediately I 
following a slash character. The leading period shall not be matched by: I 


3500 


• The asterisk or question-mark special characters 


3501 • A bracket expression containing a non-matching list, such as "[!a]", a range 

3502 expression, such as " [ %-0 ] ", or a character class expression, such as " [ [: punct: ] ] " 


3503 It is unspecified whether an explicit period in a bracket expression matching list, such as 

3504 " [ . abc ] ", can match a leading period in a file name. 


3505 

3506 

3507 

3508 


3. Specified patterns are matched against existing file names and path names, as appropriate. 
Each component that contains a pattern character requires read permission in the directory 
containing that component. Any component, except the last, that does not contain a 
pattern character requires search permission. For example, given the pattern: 


3509 


/foo/bar/x*/bam 


3510 

3511 

3512 

3513 

3514 

3515 


search permission is needed for directories / and foo, search and read permissions are 
needed for directory bar, and search permission is needed for each x* directory. If the 
pattern matches any existing file names or path names, the pattern shall be replaced with 
those file names and path names, sorted according to the collating sequence in effect in the 
current locale. If the pattern contains an invalid bracket expression or does not match any 
existing file names or path names, the pattern string shall be left unchanged. 
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3516 Rationale 

3517 The caveat about a slash within a bracket expression is derived from historical practice. The 

3518 pattern "a [b/c] d" does not match such path names as abd or a/d. On some systems (including 

3519 those conforming to the Single UNIX Specification), it matched a path name of literally 

3520 "a [b/c] d". On other systems, it produced an undefined condition (an unescaped ' [' used 

3521 outside a bracket expression). In this version, the XSI behavior is now required. 

3522 Filenames beginning with a period historically have been specially protected from view on 

3523 UNIX systems. A proposal to allow an explicit period in a bracket expression to match a leading 

3524 period was considered; it is allowed as an implementation extension, but a conforming 

3525 application cannot make use of it. If this extension becomes popular in the future, it will be 

3526 considered for a future version of this volume of IEEE Std. 1003.1-200x. 

3527 Historical systems have varied in their permissions requirements. To match f*/bar has required 

3528 read permissions on the f* directories in the System V shell, but this volume of 

3529 IEEE Std. 1003.1-200x, the C shell, and KomShell require only search permissions. 
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3530 2.14 Special Built-In Utilities 

3531 The following special built-in utilities shall be supported in the shell command language. The 

3532 output of each command, if any, shall be written to standard output, subject to the normal 

3533 redirection and piping possible with all commands. 

3534 The term built-in implies that the shell can execute the utility directly and does not need to 

3535 search for it. An implementation can choose to make any utility a built-in; however, the special 

3536 built-in utilities described here differ from regular built-in utilities in two respects: 


3537 

3538 

3539 

3540 

3541 


1. A syntax error in a special built-in utility may cause a shell executing that utility to abort, 
while a syntax error in a regular built-in utility shall not cause a shell executing that utility 
to abort. (See Section 2.8.1 on page 65 for the consequences of errors on interactive and 
non-interactive shells.) If a special built-in utility encountering a syntax error does not 
abort the shell, its exit value shall be non-zero. 


3542 2. Variable assignments specified with special built-in utilities remain in effect after the 

3543 built-in completes; this shall not be the case with a regular built-in or other utility. 


3544 The special built-in utilities in this section need not be provided in a manner accessible via the 

3545 exec family of functions defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 


3546 Some of the special built-ins are described as conforming to the System Interface Definitions I 

3547 volume of IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. For those that are not, I 

3548 the requirement in Section 1.11 on page 25 that "—" be recognized as a first argument to be 

3549 discarded does not apply and a portable application shall not use that argument. I 
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3550 NAME 

3551 break — exit from for, while, or until loop 

3552 SYNOPSIS 

3553 break [n] 

3554 DESCRIPTION 

3555 The break utility shall exit from the smallest enclosing for, while, or until loop, if any; or from the 

3556 nth enclosing loop if n is specified. The value of n is an unsigned decimal integer greater than or 

3557 equal to 1. The default shall be equivalent to n=\. If n is greater than the number of enclosing 

3558 loops, the last enclosing loop shall be exited from. Execution shall continue with the command 

3559 immediately following the loop. 

3560 OPTIONS 

3561 None. 

3562 OPERANDS 

3563 None. 

3564 STDIN 

3565 None. 

3566 INPUT FILES 

3567 None. 

3568 ENVIRONMENT VARIABLES 

3569 None. 

3570 ASYNCHRONOUS EVENTS 

3571 None. 

3572 STDOUT 

3573 None. 

3574 STDERR 

3575 None. 

3576 OUTPUT FILES 

3577 None. 

3578 EXTENDED DESCRIPTION 

3579 None. 

3580 EXIT STATUS 

3581 0 Successful completion. 

3582 >0 The n value was not an unsigned decimal integer greater than or equal to 1. 

3583 CONSEQUENCES OF ERRORS 

3584 None. 
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3585 APPLICATION USAGE 

3586 None. 

3587 EXAMPLES 

3588 for i in * do 

3589 if test —d "$i" then break fi done 

3590 RATIONALE 

3591 In early proposals, consideration was given to expanding the syntax of break and continue to refer 

3592 to a label associated with the appropriate loop as a preferable alternative to the n method. 

3593 However, this volume of IEEE Std. 1003.1-200x does reserve the namespace of command names 

3594 ending with a colon. It is anticipated that a future implementation could take advantage of this 

3595 and provide something like: 

3596 outofloop: for i in a b c d e 

3597 do 

3598 for j in 0123456789 

3599 do 

3600 if test —r "${i}${j}" 

3601 then break outofloop 

3602 fi 

3603 done 

3604 done 

3605 and that this might be standardized after implementation experience is achieved. 

3606 FUTURE DIRECTIONS 

3607 None. 

3608 SEE ALSO 

3609 Section 2.14 on page 96 

3610 CHANGE HISTORY 

3611 None. 
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3612 NAME 

3613 colon — null utility 

3614 SYNOPSIS 

3615 : [argument . . .] 

3616 DESCRIPTION 

3617 This utility shall only expand command arguments. It is used when a command is needed, as in 

3618 the then condition of an if command, but nothing is to be done by the command. 

3619 OPTIONS 

3620 None. 

3621 OPERANDS 

3622 None. 

3623 STDIN 

3624 None. 

3625 INPUT FILES 

3626 None. 

3627 ENVIRONMENT VARIABLES 

3628 None. 

3629 ASYNCHRONOUS EVENTS 

3630 None. 

3631 STDOUT 

3632 None. 

3633 STDERR 

3634 None. 

3635 OUTPUT FILES 

3636 None. 

3637 EXTENDED DESCRIPTION 

3638 None. 

3639 EXIT STATUS 

3640 Zero. 

3641 CONSEQUENCES OF ERRORS 

3642 None. 

3643 APPLICATION USAGE 

3644 None. 

3645 EXAMPLES 

3646 : ${X 

3647 if 

3648 then 

3649 else 

3650 fi 

3651 abc 

3652 As with any of the special built-ins, the null utility can also have variable assignments and 

3653 redirections associated with it, such as: 


=abc} 
false 

echo $X 
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3654 x=y : > z 

3655 which sets variable x to the value y (so that it persists after the null utility completes) and creates 

3656 or truncates file z. 

3657 RATIONALE 

3658 None. 

3659 FUTURE DIRECTIONS 

3660 None. 

3661 SEE ALSO 

3662 Section 2.14 on page 96 

3663 CHANGE HISTORY 

3664 None. 
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3665 NAME 

3666 continue — continue for, while, or until loop 

3667 SYNOPSIS 

3668 continue [n] 

3669 DESCRIPTION 

3670 The continue utility shall return to the top of the smallest enclosing for, while, or until loop, or to 

3671 the top of the nth enclosing loop, if n is specified. This involves repeating the condition list of a 

3672 while or until loop or performing the next assignment of a for loop, and reexecuting the loop if 

3673 appropriate. 

3674 The value of n is a decimal integer greater than or equal to 1. The default is equivalent to n=l. If 

3675 n is greater than the number of enclosing loops, the last enclosing loop shall be used. 

3676 OPTIONS 

3677 None. 

3678 OPERANDS 

3679 None. 

3680 STDIN 

3681 None. 

3682 INPUT FILES 

3683 None. 

3684 ENVIRONMENT VARIABLES 

3685 None. 

3686 ASYNCHRONOUS EVENTS 

3687 None. 

3688 STDOUT 

3689 None. 

3690 STDERR 

3691 None. 

3692 OUTPUT FILES 

3693 None. 

3694 EXTENDED DESCRIPTION 

3695 None. 

3696 EXIT STATUS 

3697 0 Successful completion. 

3698 >0 The n value was not an unsigned decimal integer greater than or equal to 1. 

3699 CONSEQUENCES OF ERRORS 

3700 None. 
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3701 APPLICATION USAGE 

3702 None. 

3703 EXAMPLES 

3704 for i in * 

3705 do 

3706 if test —d "$i" 

3707 then continue 

3708 fi 

3709 echo "\"$i\"" is not a directory. 

3710 done 

3711 RATIONALE 

3712 None. 

3713 FUTURE DIRECTIONS 

3714 None. 

3715 SEE ALSO 

3716 Section 2.14 on page 96 

3717 CHANGE HISTORY 

3718 None. 
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3719 NAME 

3720 dot — execute commands in current environment 

3721 SYNOPSIS 

3722 . file 

3723 DESCRIPTION 

3724 The shell shall execute commands from the file in the current environment. 

3725 If file does not contain a slash, the shell shall use the search path specified by PATH to find the 

3726 directory containing file. Unlike normal command search, however, the file searched for by the 

3727 dot utility need not be executable. If no readable file is found, a non-interactive shell shall abort; 

3728 an interactive shell shall write a diagnostic message to standard error, but this condition shall 

3729 not be considered a syntax error. 

3730 OPTIONS 

3731 None. 

3732 OPERANDS 

3733 None. 

3734 STDIN 

3735 None. 

3736 INPUT FILES 

3737 None. 

3738 ENVIRONMENT VARIABLES 

3739 None. 

3740 ASYNCHRONOUS EVENTS 

3741 None. 

3742 STDOUT 

3743 None. 

3744 STDERR 

3745 None. 

3746 OUTPUT FILES 

3747 None. 

3748 EXTENDED DESCRIPTION 

3749 None. 

3750 EXIT STATUS 

3751 Returns the value of the last command executed, or a zero exit status if no command is executed. 

3752 CONSEQUENCES OF ERRORS 

3753 None. 

3754 APPLICATION USAGE 

3755 None. 

3756 EXAMPLES 

3757 cat foobar 

3758 foo=hello bar=world 

3759 . foobar 

3760 echo $foo $bar 

3761 hello world 
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3762 RATIONALE 

3763 Some older implementations searched the current directory for the file, even if the value of PATH 

3764 disallowed it. This behavior was omitted from this volume of IEEE Std. 1003.1-200x due to 

3765 concerns about introducing the susceptibility to trojan horses that the user might be trying to 

3766 avoid by leaving dot out of PATH. 

3767 The KomShell version of dot takes optional arguments that are set to the positional parameters. 

3768 This is a valid extension that allows a dot script to behave identically to a function. 

3769 FUTURE DIRECTIONS 

3770 None. 

3771 SEE ALSO 

3772 Section 2.14 on page 96 

3773 CHANGE HISTORY 

3774 None. 
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3775 NAME 

3776 eval — construct command by concatenating arguments 

3777 SYNOPSIS 

3778 eval [argument . . .] 

3779 DESCRIPTION 

3780 The eval utility shall construct a command by concatenating arguments together, separating each 

3781 with a <space> character. The constructed command shall be read and executed by the shell. 

3782 OPTIONS 

3783 None. 

3784 OPERANDS 

3785 None. 

3786 STDIN 

3787 None. 

3788 INPUT FILES 

3789 None. 

3790 ENVIRONMENT VARIABLES 

3791 None. 

3792 ASYNCHRONOUS EVENTS 

3793 None. 

3794 STDOUT 

3795 None. 

3796 STDERR 

3797 None. 

3798 OUTPUT FILES 

3799 None. 

3800 EXTENDED DESCRIPTION 

3801 None. 

3802 EXIT STATUS 

3803 If there are no arguments, or only null arguments, eval shall return a zero exit status; otherwise, it 

3804 shall return the exit status of the command defined by the string of concatenated arguments 

3805 separated by spaces. 

3806 CONSEQUENCES OF ERRORS 

3807 None. 

3808 APPLICATION USAGE 

3809 None. 

3810 EXAMPLES 

3811 foo=10 x=foo 

3812 y='$'$x 

3813 echo $y 

3814 $foo 

3815 eval y=' $' $x 

3816 echo $y 

3817 10 
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3818 

RATIONALE 


3819 

None. 


3820 

FUTURE DIRECTIONS 


3821 

None. 


3822 

SEE ALSO 


3823 

Section 2.14 on page 96 


3824 

CHANGE HISTORY 


3825 

None. 
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3826 NAME 

3827 exec — execute commands and open, close, or copy file descriptors 

3828 SYNOPSIS 

3829 exec [ command [argument ...]] 

3830 DESCRIPTION 

3831 The exec utility shall open, close, and/or copy file descriptors as specified by any redirections as 

3832 part of the command. 

3833 If exec is specified without command or arguments, and any file descriptors with numbers greater 

3834 than 2 are opened with associated redirection statements, it is unspecified whether those file 

3835 descriptors remain open when the shell invokes another utility. Scripts concerned that child 

3836 shells could misuse open file descriptors can always close them explicitly, as shown in one of the 

3837 following examples. 

3838 If exec is specified with command, it shall replace the shell with command without creating a new 

3839 process. If arguments are specified, they shall be arguments to command. Redirection affects the 

3840 current shell execution environment. 

3841 OPTIONS 

3842 None. 

3843 OPERANDS 

3844 None. 

3845 STDIN 

3846 None. 

3847 INPUT FILES 

3848 None. 

3849 ENVIRONMENT VARIABLES 

3850 None. 

3851 ASYNCHRONOUS EVENTS 

3852 None. 

3853 STDOUT 

3854 None. 

3855 STDERR 

3856 None. 

3857 OUTPUT FILES 

3858 None. 

3859 EXTENDED DESCRIPTION 

3860 None. 

3861 EXIT STATUS 

3862 If command is specified, exec shall not return to the shell; rather, the exit status of the process shall 

3863 be the exit status of the program implementing command, which overlaid the shell. If command is 

3864 not found, the exit status shall be 127. If command is found, but it is not an executable utility, the 

3865 exit status shall be 126. If a redirection error occurs (see Section 2.8.1 on page 65), the shell shall 

3866 exit with a value in the range 1-125. Otherwise, exec shall return a zero exit status. 
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3867 CONSEQUENCES OF ERRORS 

3868 None. 

3869 APPLICATION USAGE 

3870 None. 

3871 EXAMPLES 

3872 Open readfile as file descriptor 3 for reading: 

3873 exec 3< readfile 

3874 Open zvritefile as file descriptor 4 for writing: 

3875 exec 4> writefile 

3876 Make file descriptor 5 a copy of file descriptor 0: 

3877 exec 5<&0 

3878 Close file descriptor 3: 

3879 exec 3<&- 

3880 Cat the file maggie by replacing the current shell with the cat utility: 

3881 exec cat maggie 

3882 RATIONALE 

3883 Most historical implementations were not conformant in that: 

3884 foo=bar exec cmd 

3885 did not pass too to cmd. 

3886 FUTURE DIRECTIONS 

3887 None. 

3888 SEE ALSO 

3889 Section 2.14 on page 96 

3890 CHANGE HISTORY 

3891 None. 
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3892 NAME 

3893 exit — cause the shell to exit 

3894 SYNOPSIS 

3895 exit [n] 

3896 DESCRIPTION 

3897 The exit utility shall cause the shell to exit with the exit status specified by the unsigned decimal 

3898 integer n. If n is specified, but its value is not between 0 and 255 inclusively, the exit status is 

3899 undefined. 

3900 A trap on EXIT shall be executed before the shell terminates, except when the exit utility is 

3901 invoked in that trap itself, in which case the shell shall exit immediately. 

3902 OPTIONS 

3903 None. 

3904 OPERANDS 

3905 None. 

3906 STDIN 

3907 None. 

3908 INPUT FILES 

3909 None. 

3910 ENVIRONMENT VARIABLES 

3911 None. 

3912 ASYNCHRONOUS EVENTS 

3913 None. 

3914 STDOUT 

3915 None. 

3916 STDERR 

3917 None. 

3918 OUTPUT FILES 

3919 None. 

3920 EXTENDED DESCRIPTION 

3921 None. 

3922 EXIT STATUS 

3923 The exit status shall be n, if specified. Otherwise, the value shall be the exit value of the last 

3924 command executed, or zero if no command was executed. When exit is executed in a trap action, 

3925 the last command is considered to be the command that executed immediately preceding the 

3926 trap action. 

3927 CONSEQUENCES OF ERRORS 

3928 None. 

3929 APPLICATION USAGE 

3930 None. 

3931 EXAMPLES 

3932 Exit with a true value: 

3933 exit 0 
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3934 Exit with & false value: 

3935 exit 1 

3936 RATIONALE 

3937 As explained in other sections, certain exit status values have been reserved for special uses and 

3938 should be used by applications only for those purposes: 

3939 1 26 A file to be executed was found, but it was not an executable utility. 

3940 1 27 A utility to be executed was not found. 

3941 >128 A command was interrupted by a signal. 

3942 FUTURE DIRECTIONS 

3943 None. 

3944 SEE ALSO 

3945 Section 2.14 on page 96 

3946 CHANGE HISTORY 

3947 None. 
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3948 NAME 

3949 export — set export attribute for variables 

3950 SYNOPSIS 

3951 export name [=word] . . . 

3952 export — p 

3953 DESCRIPTION 

3954 The shell shall give the export attribute to the variables corresponding to the specified names, 

3955 which shall cause them to be in the environment of subsequently executed commands. 

3956 The export special built-in shall support the System Interface Definitions volume of I 

3957 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

3958 When -p is specified, export shall write to the standard output the names and values of all 

3959 exported variables, in the following format: 

3960 "export %s=%s\n", <name>, <value> 

3961 The shell shall format the output, including the proper use of quoting, so that it is suitable for 

3962 reinput to the shell as commands that achieve the same exporting results. 

3963 When no arguments are given, the results are unspecified. 

3964 OPTIONS 

3965 None. 

3966 OPERANDS 

3967 None. 

3968 STDIN 

3969 None. 

3970 INPUT FILES 

3971 None. 

3972 ENVIRONMENT VARIABLES 

3973 None. 

3974 ASYNCHRONOUS EVENTS 

3975 None. 

3976 STDOUT 

3977 None. 

3978 STDERR 

3979 None. 

3980 OUTPUT FILES 

3981 None. 

3982 EXTENDED DESCRIPTION 

3983 None. 

3984 EXIT STATUS 

3985 Zero. 
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3986 CONSEQUENCES OF ERRORS 

3987 None. 

3988 APPLICATION USAGE 

3989 None. 

3990 EXAMPLES 

3991 Export PWD and HOME variables: 

3992 export PWD HOME 

3993 Set and export the PATH variable: 

3994 export PATH=/local/bin : $PATH 

3995 Save and restore all exported variables: 

3996 export —p > temp-file 

3997 unset a lot of variables 

3998 . . . processing 

3999 . temp-file 

4000 RATIONALE 

4001 Some historical shells use the no-argument case as the functional equivalent of what is required 

4002 here with -p. This feature was left unspecified because it is not historical practice in all shells, 

4003 and some scripts may rely on the now-unspecified results on their implementations. Attempts to 

4004 specify the -p output as the default case were unsuccessful in achieving consensus. The -p 

4005 option was added to allow portable access to the values that can be saved and then later restored 

4006 using; for example, a dot script. 

4007 FUTURE DIRECTIONS 

4008 None. 

4009 SEE ALSO 

4010 Section 2.14 on page 96 

4011 CHANGE HISTORY 

4012 None. 
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4013 NAME 

4014 readonly — set read-only attribute for variables 

4015 SYNOPSIS 

4016 readonly name [ = word] . . . 

4017 readonly —p 

4018 DESCRIPTION 

4019 The variables whose names are specified shall be given the readonly attribute. The values of 

4020 variables with the readonly attribute cannot be changed by subsequent assignment, nor can those 

4021 variables be unset by the unset utility. 

4022 The readonly special built-in shall support the System Interface Definitions volume of I 

4023 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

4024 When -p is specified, readonly writes to the standard output the names and values of all read- 

4025 only variables, in the following format: 

4026 "readonly %s=%s\n", <name>, <value> 

4027 The shell shall format the output, including the proper use of quoting, so that it is suitable for 

4028 reinput to the shell as commands that achieve the same attribute-setting results. 

4029 When no arguments are given, the results are unspecified. 

4030 OPTIONS 

4031 None. 

4032 OPERANDS 

4033 None. 

4034 STDIN 

4035 None. 

4036 INPUT FILES 

4037 None. 

4038 ENVIRONMENT VARIABLES 

4039 None. 

4040 ASYNCHRONOUS EVENTS 

4041 None. 

4042 STDOUT 

4043 None. 

4044 STDERR 

4045 None. 

4046 OUTPUT FILES 

4047 None. 

4048 EXTENDED DESCRIPTION 

4049 None. 

4050 EXIT STATUS 

4051 Zero. 
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4052 CONSEQUENCES OF ERRORS 

4053 None. 

4054 APPLICATION USAGE 

4055 None. 

4056 EXAMPLES 

4057 readonly HOME PWD 

4058 RATIONALE 

4059 Some historical shells preserve the read-only attribute across separate invocations. This volume 

4060 of IEEE Std. 1003.1-200x allows this behavior, but does not require it. 

4061 The -p option allows portable access to the values that can be saved and then later restored 

4062 using; for example, a dot script. Also see the RATIONALE for export on page 111 for a 

4063 description of the no-argument and -p output cases and a related example. 

4064 Read-only functions were considered, but they were omitted as not being historical practice or 

4065 particularly useful. Furthermore, functions must not be readonly across invocations to preclude 

4066 spoofing (spoofing is the term for the practice of creating a program that acts like a well-known 

4067 utility with the intent of subverting the real intent of the user) of administrative or security- 

4068 relevant (or security-conscious) shell scripts. 

4069 FUTURE DIRECTIONS 

4070 None. 

4071 SEE ALSO 

4072 Section 2.14 on page 96 

4073 CHANGE HISTORY 

4074 None. 
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4075 NAME 

4076 return — return from a function 

4077 SYNOPSIS 

4078 return [n] 

4079 DESCRIPTION 

4080 The return utility shall cause the shell to stop executing the current function or dot script. If the 

4081 shell is not currently executing a function or dot script, the results are unspecified. 

4082 OPTIONS 

4083 None. 

4084 OPERANDS 

4085 None. 

4086 STDIN 

4087 None. 

4088 INPUT FILES 

4089 None. 

4090 ENVIRONMENT VARIABLES 

4091 None. 

4092 ASYNCHRONOUS EVENTS 

4093 None. 

4094 STDOUT 

4095 None. 

4096 STDERR 

4097 None. 

4098 OUTPUT FILES 

4099 None. 

4100 EXTENDED DESCRIPTION 

4101 None. 

4102 EXIT STATUS 

4103 The value of the special parameter ' ?' shall be set to n, an unsigned decimal integer, or to the 

4104 exit status of the last command executed if n is not specified. If the value of n is greater than 255, 

4105 the results are undefined. When return is executed in a trap action, the last command is 

4106 considered to be the command that executed immediately preceding the trap action. 

4107 CONSEQUENCES OF ERRORS 

4108 None. 

4109 APPLICATION USAGE 

4110 None. 

4111 EXAMPLES 

4112 None. 

4113 RATIONALE 

4114 The behavior of return when not in a function or dot script differs between the System V shell 

4115 and the KomShell. In the System V shell this is an error, whereas in the KomShell, the effect is 

4116 the same as exit. 
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4117 

The results of returning a number greater than 255 are undefined because 

of differing practices 

4118 

in the various historical implementations. Some shells AND out all but 

the low-order 8 bits; 

4119 

others allow larger values, but not of unlimited size. 


4120 

See the discussion of appropriate exit status values under exit on page 109. 


4121 

FUTURE DIRECTIONS 


4122 

None. 


4123 

SEE ALSO 


4124 

Section 2.14 on page 96 


4125 

CHANGE HISTORY 


4126 

None. 
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4127 NAME 

4128 set — set or unset options and positional parameters 

4129 SYNOPSIS 

4130 xsi set [— abCefmnuvx] [—h] [—o option] [argument. . .] 

4131 xsi set [+abCefmnuvx] [+h] [+o option] [argument. . .] 

4132 set — [argument...] 

4133 set —o 

4134 set +o 

4135 DESCRIPTION 

4136 If no options or arguments are specified, set shall write the names and values of all shell variables 

4137 in the collation sequence of the current locale. Each name shall start on a separate line, using the 

4138 format: 


4139 "%s=%s\n", <name >, <value> 

4140 The value string shall be written with appropriate quoting so that it is suitable for reinput to the 

4141 shell, setting or resetting, as far as possible, the variables that are currently set. Read-only 

4142 variables cannot be reset; see the description of shell quoting in Section 2.2 on page 36. 

4143 When options are specified, they shall set or unset attributes of the shell, as described below. 

4144 When arguments are specified, they cause positional parameters to be set or unset, as described 

4145 below. Setting or unsetting attributes and positional parameters are not necessarily related 

4146 actions, but they can be combined in a single invocation of set. 

4147 The set special built-in shall support the System Interface Definitions volume of I 

4148 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines except that options can be specified I 

4149 with either a leading hyphen (meaning enable the option) or plus sign (meaning disable it). 

4150 Implementations shall support the options in the following list in both their hyphen and plus- 

4151 sign forms. These options can also be specified as options to sh. 

4152 -a When this option is on, the export attribute shall be set for each variable to which an I 

4153 assignment is performed; see the System Interface Definitions volume of I 

4154 IEEE Std. 1003.1-200x, Section 3.426, Variable Assignment. If the assignment precedes a I 

4155 utility name in a command, the export attribute shall not persist in the current execution 

4156 environment after the utility completes, with the exception that preceding one of the special 

4157 built-in utilities causes the export attribute to persist after the built-in has completed. If the 

4158 assignment does not precede a utility name in the command, or if the assignment is a result 

4159 of the operation of the getopts or read utilities, the export attribute shall persist until the 

4160 variable is unset. 

4161 -b This option is supported if the system supports the User Portability Utilities option. It shall 

4162 cause the shell to notify the user asynchronously of background job completions. The 

4163 following message is written to standard error: 

4164 "[%d]%c %s%s\n", <job-number >, <current>, <status>, <job-name> 

4165 where the fields shall be as follows: 


4166 

4167 

4168 

4169 

4170 


<current> The character ' +' identifies the job that would be used as a default for 

the fg or bg utilities; this job can also be specified using the job_id " %+" or 
" %%". The character ' identifies the job that would become the default 
if the current default job were to exit; this job can also be specified using 
th e job_id For other jobs, this field is a <space> character. At most 
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4171 

4172 

4173 

4174 


one job can be identified with ' +' and at most one job can be identified 
with ' —'. If there is any suspended job, then the current job shall be a 
suspended job. If there are at least two suspended jobs, then the previous 
job also shall be a suspended job. 


4175 

4176 

4177 


<job-number> A number that can be used to identify the process group to the wait,fg, bg, 
and kill utilities. Using these utilities, the job can be identified by 
prefixing the job number with ' %'. 


4178 


<status> 


Unspecified. 


4179 


<job-name> Unspecified. 


4180 When the shell notifies the user a job has been completed, it may remove the job's process 

4181 ID from the list of those known in the current shell execution environment; see Section 

4182 2.9.3.1 on page 74. Asynchronous notification shall not be enabled by default. 


4183 -C (Uppercase C.) Prevent existing files from being overwritten by the shell's ' >' redirection 

4184 operator (see Section 2.7.2 on page 61); the "> | " redirection operator shall override this 

4185 noclobber option for an individual file. 


4186 

4187 

4188 

4189 


-e When this option is on, if a simple command fails for any of the reasons listed in Section 
2.8.1 on page 65 or returns an exit status value >0, and is not part of the compound list 
following a while, until, or if key wo rd, and is not a part of an AND or OR list, and is not a 
pipeline preceded by the ! reserved word, then the shell shall immediately exit. 


4190 

4191 XSI 

4192 


-f The shell shall disable path name expansion. 

-h Locate and remember utilities invoked by functions as those functions are defined (the 
utilities are normally located when the function is executed). 


4193 

4194 

4195 

4196 

4197 

4198 

4199 

4200 


-m This option is supported if the system supports the User Portability Utilities option. All jobs 
shall be run in their own process groups. Immediately before the shell issues a prompt after 
completion of the background job, a message reporting the exit status of the background job 
shall be written to standard error. If a foreground job stops, the shell shall write a message 
to standard error to that effect, formatted as described by the jobs utility. In addition, if a job 
changes status other than exiting (for example, if it stops for input or output or is stopped 
by a SIGSTOP signal), the shell shall write a similar message immediately prior to writing 
the next prompt. This option is enabled by default for interactive shells. 


4201 

4202 

4203 

4204 

4205 


-n The shell shall read commands but does not execute them; this can be used to check for 
shell script syntax errors. An interactive shell may ignore this option. I 

-o Write the current settings of the options to standard output in an unspecified format. I 

+o Write the current option settings to standard output in a format that is suitable for reinput I 
to the shell as commands that achieve the same options settings. I 


4206 -o option 

4207 This option is supported if the system supports the User Portability Utilities option. It shall 

4208 set various options, many of which shall be equivalent to the single option letters. The 

4209 following values of option shall be supported: 


4210 


allexport Equivalent to -a. 


4211 


err exit Equivalent to -e. 


4212 

4213 

4214 


ignoreeof Prevent an interactive shell from exiting on end-of-file. This setting prevents I 
accidental logouts when control-D is entered. A user shall explicitly exit to I 
leave the interactive shell. 
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4215 

4216 

4217 

4218 

4219 


monitor 

noclobber 

noglob 

noexec 


Equivalent to -m. This option is supported if the system supports the User 
Portability Utilities option. 

Equivalent to -C (uppercase C). 

Equivalent to -f. 

Equivalent to -n. 


4220 man nolog Prevent the entry of function definitions into the command history; see 

4221 Command History List on page 892. 


4222 

4223 

4224 

4225 

4226 

4227 

4228 

4229 


notify Equivalent to -b. 

nonnset Equivalent to -u. 

verbose Equivalent to -v. 

vi Allow shell command line editing using the built-in vi editor. Enabling vi I 

mode shall disable any other command line editing mode provided as an I 
implementation extension. 

It need not be possible to set vi mode on for certain block-mode terminals. 
xtrace Equivalent to -x. 


4230 

4231 


-u The shell writes a message to standard error when it tries to expand a variable that is not set 
and immediately exit. An interactive shell shall not exit. 


4232 


-v The shell writes its input to standard error as it is read. 


4233 

4234 

4235 


-x The shell writes to standard error a trace for each command after it expands the command I 
and before it executes it. It is unspecified whether the command that turns tracing off is I 
traced. I 


4236 The default for all these options is off (unset) unless the shell was invoked with them on; see sh. 

4237 The remaining arguments shall be assigned in order to the positional parameters. The special 

4238 parameter ' #' shall be set to reflect the number of positional parameters. All positional 

4239 parameters shall be unset before any new values are assigned. 

4240 The special argument "—" immediately following the set command name can be used to delimit 

4241 the arguments if the first argument begins with ' +' or ' , or to prevent inadvertent listing of 

4242 all shell variables when there are no arguments. The command set — without argument shall 

4243 unset all positional parameters and set the special parameter ' #' to zero. 

4244 OPTIONS 

4245 None. 


4246 OPERANDS 

4247 None. 


4248 STDIN 

4249 None. 


4250 INPUT FILES 

4251 None. 


4252 ENVIRONMENT VARIABLES 

4253 None. 
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4254 ASYNCHRONOUS EVENTS 

4255 None. 

4256 STDOUT 

4257 None. 

4258 STDERR 

4259 None. 

4260 OUTPUT FILES 

4261 None. 

4262 EXTENDED DESCRIPTION 

4263 None. 

4264 EXIT STATUS 

4265 Zero. 

4266 CONSEQUENCES OF ERRORS 

4267 None. 

4268 APPLICATION USAGE 

4269 None. 

4270 EXAMPLES 

4271 Write out all variables and their values: 

4272 set 

4273 Set $1, $2, and $3 and set " $ #" to 3: 

4274 set cab 

4275 Turn on the -x and -v options: 

4276 set —xv 

4277 Unset all positional parameters: 

4278 set — 

4279 Set $1 to the value of -x, even if x begins with ' - ' or ' +': 

4280 set — "$x" 

4281 Set the positional parameters to the expansion of x, even if x expands with a leading ' - ' or ' +': 

4282 set — $ x 

4283 RATIONALE 

4284 The set — form is listed specifically in the SYNOPSIS even though this usage is implied by the 

4285 Utility Syntax Guidelines. The explanation of this feature removes any ambiguity about whether 

4286 the set — form might be misinterpreted as being equivalent to set without any options or 

4287 arguments. The functionality of this form has been adopted from the KornShell. In System V, set 

4288 — only unsets parameters if there is at least one argument; the only way to unset all parameters 

4289 is to use shift. Using the KornShell version should not affect System V scripts because there 

4290 should be no reason to issue it without arguments deliberately; if it were issued as, for example: 

4291 set — "$@" 

4292 and there were in fact no arguments resulting from " $@unsetting the parameters would have 

4293 no result. 


120 


Technical Standard (2000) (Draft February 29, 2000) 



Shell Command Language 


set 


4294 The set + form in early proposals was omitted as being an unnecessary duplication of set alone 

4295 and not widespread historical practice. 

4296 The noclobber option was changed to allow set -C as well as the set -o noclobber option. The 

4297 single-letter version was added so that the historical " $-" paradigm would not be broken; see 

4298 Section 2.5.2 on page 43. 

4299 The -h flag is related to command name hashing and is only required on XSI-conformant 

4300 systems. 

4301 The following set flags were omitted intentionally with the following rationale: 

4302 -k The -k flag was originally added by the author of the Bourne shell to make it easier for 

4303 users of pre-release versions of the shell. In early versions of the Bourne shell the construct 

4304 set name-value, had to be used to assign values to shell variables. The problem with -k is 

4305 that the behavior affects parsing, virtually precluding writing any compilers. To explain the 

4306 behavior of -k, it is necessary to describe the parsing algorithm, which is implementation- 

4307 dependent. For example: 

4308 set — k; echo name=value 

4309 and: 

4310 set x—k 

4311 echo name=value 

4312 behave differently. The interaction with functions is even more complex. What is more, the 

4313 -k flag is never needed, since the command line could have been reordered. 

4314 -t The -t flag is hard to specify and almost never used. The only known use could be done 

4315 with here-documents. Moreover, the behavior with ksh and sh differs. The reference page 

4316 says that it exits after reading and executing one command. What is one command? If the 

4317 input is date;date, sh executes both date commands while ksh does only the first. 

4318 Consideration was given to rewriting set to simplify its confusing syntax. A specific suggestion 

4319 was that the unset utility should be used to unset options instead of using the non-getopt ()-able 

4320 +option syntax. However, the conclusion was reached that the historical practice of using +option 

4321 was satisfactory and that there was no compelling reason to modify such widespread historical 

4322 practice. 

4323 The -o option was adopted from the KomShell to address user needs. In addition to its generally 

4324 friendly interface, -o is needed to provide the vi command line editing mode, for which I 

4325 historical practice yields no single-letter option name. (Although it might have been possible to I 

4326 invent such a letter, it was recognized that other editing modes would be developed and -o 

4327 provides ample name space for describing such extensions.) 

4328 Historical implementations are inconsistent in the format used for -o option status reporting. I 

4329 The +0 format without an option-argument was added to allow portable access to the options I 

4330 that can be saved and then later restored using, for instance, a dot script. I 

4331 Historically, sh did trace the command set +x, but ksh did not. I 

4332 It is not possible to use the " $-" special parameter to determine the current setting of either of I 

4333 these two modes. In the KomShell, the option option-argument can be omitted, producing a 

4334 report of current option settings. Since it breaks the Utility Syntax Guidelines, and since the 

4335 output format was unspecified (it changed between KomShell versions), this usage was omitted. 

4336 The ignoreeof setting prevents accidental logouts when the end-of-file character (typically I 

4337 control-D) is entered. A user shall explicitly exit to leave the interactive shell. I 
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4338 The set -m option was added to apply only to the UPE because it applies primarily to interactive 

4339 use, not shell script applications. 

4340 The ability to do asynchronous notification became available in the 1988 version of the 

4341 KomShell. To have it occur, the user had to issue the command: 

4342 trap "jobs —n" CLD 

4343 The C shell provides two different levels of an asynchronous notification capability. The 

4344 environment variable notify is analogous to what is done in set -b or set -o notify . When set, it 

4345 notifies the user immediately of background job completions. When unset, this capability is 

4346 turned off. 

4347 The other notification ability comes through the built-in utility notify. The syntax is: 

4348 notify [%job ... ] 

4349 By issuing notify with no operands, it causes the C shell to notify the user asynchronously when 

4350 the state of the current job changes. If given operands, notify asynchronously informs the user of 

4351 changes in the states of the specified jobs. 

4352 To add asynchronous notification to the POSIX shell, neither the KomShell extensions to trap, 

4353 nor the C shell notify environment variable seemed appropriate ( notify is not a proper POSIX 

4354 environment variable name). 

4355 The set -b option was selected as a compromise. 

4356 The notify built-in was considered to have more functionality than was required for simple 

4357 asynchronous notification. 

4358 FUTURE DIRECTIONS 

4359 None. 

4360 SEE ALSO 

4361 Section 2.14 on page 96 

4362 CHANGE HISTORY 

4363 Issue 6 

4364 The obsolescent set command name followed by ' —' has been removed. 

4365 The following new requirements on POSIX implementations derive from alignment with the 

4366 Single UNIX Specification: 

4367 • The nolog option is added to set -o. 
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4368 NAME 

4369 shift — shift positional parameters 

4370 SYNOPSIS 

4371 shift [n] 

4372 DESCRIPTION 

4373 The positional parameters shall be shifted. Positional parameter 1 shall be assigned the value of 

4374 parameter (1+n), parameter 2 shall be assigned the value of parameter (2 +n), and so on. The 

4375 parameters represented by the numbers "$#" down to "$#-n+l" shall be unset, and the 

4376 parameter ' #' is updated to reflect the new number of positional parameters. 

4377 The value n shall be an unsigned decimal integer less than or equal to the value of the special 

4378 parameter ' #'. If n is not given, it shall be assumed to be 1. If n is 0, the positional and special 

4379 parameters are not changed. 

4380 OPTIONS 

4381 None. 

4382 OPERANDS 

4383 None. 

4384 STDIN 

4385 None. 

4386 INPUT FILES 

4387 None. 

4388 ENVIRONMENT VARIABLES 

4389 None. 

4390 ASYNCHRONOUS EVENTS 

4391 None. 

4392 STDOUT 

4393 None. 

4394 STDERR 

4395 None. 

4396 OUTPUT FILES 

4397 None. 

4398 EXTENDED DESCRIPTION 

4399 None. 

4400 EXIT STATUS 

4401 The exit status is >0 if n >$#; otherwise, it is zero. 

4402 CONSEQUENCES OF ERRORS 

4403 None. 
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4404 APPLICATION USAGE 

4405 None. 

4406 EXAMPLES 

4407 $setabcde 

4408 $ shift 2 

4409 $ echo $* 

4410 c d e 

4411 RATIONALE 

4412 None. 

4413 FUTURE DIRECTIONS 

4414 None. 

4415 SEE ALSO 

4416 Section 2.14 on page 96 

4417 CHANGE HISTORY 

4418 None. 
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4419 NAME 

4420 times — write process times 

4421 SYNOPSIS 

4422 MAN t ime s 

4423 

4424 DESCRIPTION 

4425 Write the accumulated user and system times for the shell and for all of its child processes, in the 

4426 following POSIX locale format: 

4427 "%dm%fs %dm%fs\n%dm%fs %dm%fs\n", <shell user minutes>, 

4428 <shell user seconds> , <shell system minutes >, 

4429 <shell system seconds >, <children user minutes>, 

4430 <children user seconds>, <children system minutes>, 

4431 <children system seconds> 

4432 The four pairs of times correspond to the members of the <sys/times.h> tms structure (defined I 

4433 in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers) as I 

4434 returned by times (): tms_utime, tms_stime, tmsjcutime, and tmsjcstime, respectively. I 

4435 OPTIONS 

4436 None. 

4437 OPERANDS 

4438 None. 

4439 STDIN 

4440 None. 

4441 INPUT FILES 

4442 None. 

4443 ENVIRONMENT VARIABLES 

4444 None. 

4445 ASYNCHRONOUS EVENTS 

4446 None. 

4447 STDOUT 

4448 None. 

4449 STDERR 

4450 None. 

4451 OUTPUT FILES 

4452 None. 

4453 EXTENDED DESCRIPTION 

4454 None. 

4455 EXIT STATUS 

4456 Zero. 

4457 CONSEQUENCES OF ERRORS 

4458 None. 
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4459 APPLICATION USAGE 

4460 None. 

4461 EXAMPLES 

4462 $ t ime s 

4463 0m0.43s 0ml. 11s 

4464 8m44.18s lm43.23s 

4465 RATIONALE 

4466 The times special built-in from the Single UNIX Specification is now required for all conforming 

4467 shells. 

4468 FUTURE DIRECTIONS 

4469 None. 

4470 SEE ALSO 

4471 Section 2.14 on page 96 

4472 CHANGE HISTORY 

4473 None. 
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4474 NAME 

4475 trap — trap signals 

4476 SYNOPSIS 

4477 trap [ action condition . . .] 

4478 DESCRIPTION 

4479 If action is ' , the shell shall reset each condition to the default value. If action is null (" "), the 

4480 shell shall ignore each specified condition if it arises. Otherwise, the argument action shall be read 

4481 and executed by the shell when one of the corresponding conditions arises. The action of trap 

4482 shall override a previous action (either default action or one explicitly set). The value of "$?" 

4483 after the trap action completes shall be the value it had before trap was invoked. 

4484 The condition can be EXIT, 0 (equivalent to EXIT), or a signal specified using a symbolic name, 

4485 without the SIG prefix, as listed in the tables of signal names in the <signal.h> header defined in I 

4486 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers; for I 

4487 example, HUP, INT, QUIT, TERM. Implementations may permit lowercase signal names or I 

4488 names with the SIG prefix as an extension. Setting a trap for SIGKILL or SIGSTOP produces 

4489 undefined results. 

4490 The environment in which the shell executes a trap on EXIT shall be identical to the environment 

4491 immediately after the last command executed before the trap on EXIT was taken. 

4492 Each time trap is invoked, the action argument shall be processed in a manner equivalent to: 

4493 eval "$action" 

4494 Signals that were ignored on entry to a non-interactive shell cannot be trapped or reset, although 

4495 no error need be reported when attempting to do so. An interactive shell may reset or catch 

4496 signals ignored on entry. Traps shall remain in place for a given shell until explicitly changed 

4497 with another trap command. 

4498 When a subshell is entered, traps that are not being ignored are set to the default actions. This 

4499 does not imply that the trap command cannot be used within the subshell to set new traps. 

4500 The trap command with no arguments shall write to standard output a list of commands 

4501 associated with each condition. The format shall be: 

4502 "trap — %s %s . . .\n", <action>, <condition> . . . 

4503 The shell shall format the output, including the proper use of quoting, so that it is suitable for 

4504 reinput to the shell as commands that achieve the same trapping results. For example: 

4505 save_traps = $ (trap) 

4506 

4507 eval "$save_traps" 

4508 xsi XSI-conformant systems also allow numeric signal numbers for the conditions corresponding to 

4509 the following signal names: 
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4510 

4511 

4512 XSI 

4513 

4514 

4515 

4516 

4517 

4518 

4519 The trap special built-in shall conform to the System Interface Definitions volume of I 

4520 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

4521 OPTIONS 

4522 None. 

4523 OPERANDS 

4524 None. 

4525 STDIN 

4526 None. 

4527 INPUT FILES 

4528 None. 

4529 ENVIRONMENT VARIABLES 

4530 None. 

4531 ASYNCHRONOUS EVENTS 

4532 None. 

4533 STDOUT 

4534 None. 

4535 STDERR 

4536 None. 

4537 OUTPUT FILES 

4538 None. 

4539 EXTENDED DESCRIPTION 

4540 None. 

4541 EXIT STATUS 

4542 xsi If the trap name or number is invalid, a non-zero exit status shall be returned; otherwise, zero 

4543 xsi shall be returned. For both interactive and non-interactive shells, invalid signal names or 

4544 numbers shall not be considered a syntax error and do not cause the shell to abort. 

4545 CONSEQUENCES OF ERRORS 

4546 None. 

4547 APPLICATION USAGE 

4548 None. 

4549 EXAMPLES 

4550 Write out a list of all traps and actions: 

4551 trap 

4552 Set a trap so the logout utility in the directory referred to by the HOME environment variable 

4553 executes when the shell terminates: 
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4554 trap ' $HOME/logout' EXIT 

4555 or: 

4556 trap ' $HOME/logout' 0 

4557 Unset traps on INT, QUIT, TERM, and EXIT: 

4558 trap - INT QUIT TERM EXIT 

4559 RATIONALE 

4560 Implementations may permit lowercase signal names as an extension. Implementations may 

4561 also accept the names with the SIG prefix; no known historical shell does so. The trap and kill 

4562 utilities in this volume of IEEE Std. 1003.1-200x are now consistent in their omission of the SIG 

4563 prefix for signal names. Some kill implementations do not allow the prefix, and kill -1 lists the 

4564 signals without prefixes. 

4565 Trapping SIGKILL or SIGSTOP is syntactically accepted by some historical implementations, but 

4566 it has no effect. Portable POSIX applications cannot attempt to trap these signals. 

4567 The output format is not historical practice. Since the output of historical trap commands is not 

4568 portable (because numeric signal values are not portable) and had to change to become so, an 

4569 opportunity was taken to format the output in a way that a shell script could use to save and 

4570 then later reuse a trap if it wanted. 

4571 The KornShell uses an ERR trap that is triggered whenever set -e would cause an exit. This is 

4572 allowable as an extension, but was not mandated, as other shells have not used it. 

4573 The text about the environment for the EXIT trap invalidates the behavior of some historical 

4574 versions of interactive shells which, for example, close the standard input before executing a 

4575 trap on 0. For example, in some historical interactive shell sessions the following trap on 0 would 

4576 always print"—": 

4577 trap 'read foo; echo $foo—0 

4578 FUTURE DIRECTIONS 

4579 None. 

4580 SEE ALSO 

4581 Section 2.14 on page 96 

4582 CHANGE HISTORY 

4583 Issue 6 

4584 XSI-conforming implementations provide the mapping of signal names to numbers given above 

4585 (previously this had been marked obsolescent). Other implementations need not provide this 

4586 optional mapping. 
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4587 NAME 

4588 unset — unset values and attributes of variables and functions 

4589 SYNOPSIS 

4590 unset [— fv] name . . . 

4591 DESCRIPTION 

4592 Each variable or function specified by name shall be unset. 

4593 If -v is specified, name refers to a variable name and the shell shall unset it and remove it from 

4594 the environment. Read-only variables cannot be unset. 

4595 If -f is specified, name refers to a function and the shell shall unset the function definition. 

4596 If neither -f nor -v is specified, name refers to a variable; if a variable by that name does not 

4597 exist, it is unspecified whether a function by that name, if any, shall be unset. 

4598 Unsetting a variable or function that was not previously set shall not be considered an error and 

4599 does not cause the shell to abort. 

4600 The unset special built-in shall support the System Interface Definitions volume of I 

4601 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

4602 Note that: 

4603 VARIABLE = 

4604 is not equivalent to an unset of VARIABLE; in the example, VARIABLE is set to " ". Also, the 

4605 variables that can be unset should not be misinterpreted to include the special parameters (see 

4606 Section 2.5.2 on page 43). 

4607 OPTIONS 

4608 None. 

4609 OPERANDS 

4610 None. 

4611 STDIN 

4612 None. 

4613 INPUT FILES 

4614 None. 

4615 ENVIRONMENT VARIABLES 

4616 None. 

4617 ASYNCHRONOUS EVENTS 

4618 None. 

4619 STDOUT 

4620 None. 

4621 STDERR 

4622 None. 

4623 OUTPUT FILES 

4624 None. 

4625 EXTENDED DESCRIPTION 

4626 None. 
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4627 EXIT STATUS 

4628 0 All name operands were successfully unset. 

4629 >0 At least one name could not be unset. 

4630 CONSEQUENCES OF ERRORS 

4631 None. 

4632 APPLICATION USAGE 

4633 None. 

4634 EXAMPLES 

4635 Unset VIS UAL variable: 

4636 unset —v VISUAL 

4637 Unset the functions too and bar: 

4638 unset -f foo bar 

4639 RATIONALE 

4640 Consideration was given to omitting the -f option in favor of an unfunction utility, but the 

4641 standard developers decided to retain historical practice. 

4642 The -v option was introduced because System V historically used one name space for both 

4643 variables and functions. When unset is used without options. System V historically unset either a 

4644 function or a variable, and there was no confusion about which one was intended. A portable 

4645 POSIX application can use unset without an option to unset a variable, but not a function; the -f 

4646 option must be used. 

4647 FUTURE DIRECTIONS 

4648 None. 

4649 SEE ALSO 

4650 Section 2.14 on page 96 

4651 CHANGE HISTORY 

4652 None. 
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4655 be This chapter describes the services and utilities that shall be implemented on all systems that I 

4656 claim conformance to the Batch Environment option. I 

4657 Notes to Reviewers I 

4658 This section with side shading will not appear in the final copy. - Ed. I 

4659 This text and the associated reference pages are imported from IEEE Std. 1003.2d-1994. A I 

4660 suggestion received has been to change the name to Batch Services and the abbreviated margin I 

4661 marker to BS. I 


4662 3.1 General Concepts l 

4663 3.1.1 Batch Client-Server Interaction I 

4664 Batch jobs are created and managed by batch servers. A batch client interacts with a batch server I 

4665 to access batch services on behalf of the user. In order to use batch services, a user must have I 

4666 access to a batch client. I 

4667 A batch server is a computational entity, such as a daemon process, that provides batch services. I 

4668 Batch servers route, queue, modify, and execute batch jobs on behalf of batch clients. I 

4669 The batch utilities described in this volume of IEEE Std. 1003.1-200x (and listed in Table 3-1 on I 

4670 page 134) are clients of batch services; they allow users to perform actions on the job such as I 

4671 creating, modifying, and deleting batch jobs from a shell command line. Although these batch I 

4672 utilities may be said to accomplish certain services, they actually obtain services on behalf of a I 

4673 user by means of requests to batch servers. I 
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4674 Table 3-1 Batch Utilities 


4675 

q alter 

qmove 

qrls 

qstat 

4676 

qdel 

qmsg 

qselect 

qsub 

4677 

qhold 

qrerun 

qsig 



4678 Client-server interaction takes place by means of the batch requests defined in this chapter. 

4679 Because direct access to batch jobs and queues is limited to batch servers, clients and servers of 

4680 different implementations can interoperate, since dependencies on private structures for batch 

4681 jobs and queues are limited to batch servers. Also, batch servers may be clients of other batch 

4682 servers. 

4683 3.1.2 Batch Queues 

4684 Two types of batch queue are described: routing queues and execution queues. When a batch job is 

4685 placed in a routing queue, it is a candidate for routing. A batch job is removed from routing 

4686 queues under the following conditions: 

4687 • The batch job has been routed to another queue. 

4688 • The batch job has been deleted from the batch queue. 

4689 • The batch job has been aborted. 

4690 When a batch job is placed in an execution queue, it is a candidate for execution. 

4691 A batch job is removed from an execution queue under the following conditions: 

4692 • The batch job has been executed and exited. 

4693 • The batch job has been aborted. 

4694 • The batch job has been deleted from the batch queue. 

4695 • The batch job has been moved to another queue. 

4696 Access to a batch queue is limited to the batch server that manages the batch queue. Clients 

4697 never access a batch queue or a batch job directly, either to read or write information; all client 

4698 access to batch queues or jobs takes place through batch servers. 

4699 3.1.3 Batch Job Creation 

4700 When a batch server creates a batch job on behalf of a client, it assigns a batch job identifier to 

4701 the job. A batch job identifier consists of both a sequence number that is unique among the 

4702 sequence numbers issued by that server and the name of the server. Since the batch server name 

4703 is unique within a name space, the job identifier is likewise unique within the name space. 

4704 The batch server that creates a batch job returns the batch server-assigned job identifier to the 

4705 client that requested the job creation. If the batch server routes or moves the job to another 

4706 server, it sends the job identifier with the job. Once assigned, the job identifier of a batch job 

4707 never changes. 
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4708 3.1.4 Batch Job Tracking 

4709 Since a batch job may be moved after creation, the batch server name component of the job 

4710 identifier does not always indicate the location of the job. An implementation may provide a 

4711 batch job tracking mechanism, in which case the user generally does not need to know the 

4712 location of the job. However, an implementation is not required to provide a batch job tracking 

4713 mechanism, in which case the user must find routed jobs by probing the possible destinations. 

4714 3.1.5 Batch Job Routing 

4715 To route a batch job, a batch server either moves the job to some other queue that is managed by 

4716 the batch server, or requests that some other batch server accept the job. 

4717 Each routing queue has one or more queues to which it can route batch jobs. The batch server 

4718 administrator creates routing queues. 

4719 A batch server may route a batch job from a routing queue to another routing queue. Batch 

4720 servers shall prevent or otherwise handle cases of circular routing paths. As a deferred service, a 

4721 batch server routes jobs from the routing queues that it manages. The algorithm by which a 

4722 batch server selects a batch queue to which to route a batch job is implementation-dependent. 

4723 A batch job need not be eligible for routing to all the batch queues fed by the routing queue from 

4724 which it is routed. A batch server that has been asked to accept the job may reject the request if 

4725 the job requires resources that are unavailable to that batch server, or if the client is not 

4726 authorized to access the batch server. 

4727 Batch servers may route high-priority jobs before low-priority jobs, but, on other than 

4728 overloaded systems, the effect may be imperceptible to the user. If all the batch servers fed by a 

4729 routing queue reject requests to accept the job for reasons that are permanent, the batch server 

4730 that manages the job aborts the job. If all or some rejections are temporary, the batch server 

4731 should try to route the job again at some later point. 

4732 The conformance document for an implementation shall list the reasons for rejecting the routing 

4733 of a batch job. The conformance document shall indicate the reasons for which the routing 

4734 should be retried later and the reasons for which the job should be aborted. 

4735 3.1.6 Batch Job Execution 

4736 To execute a batch job is to create a session leader (a process) that runs the shell program 

4737 indicated by the Shell_Pnth attribute of the job. The script is passed to the program as its 

4738 standard input. An implementation of the batch server may pass the script to the program by 

4739 other means. The implementation shall document the alternate means in the conformance 

4740 document. At the time a batch job begins execution, it is defined to enter the RUNNING state. 

4741 The primary program that is executed by a batch job is typically, though not necessarily, a shell 

4742 program. 

4743 A batch server executes eligible jobs as a deferred service—no client request is necessary once 

4744 the batch job is created and eligible. However, the attributes of a batch job, such as the job hold 

4745 type, may render the job ineligible. A batch server scans the execution queues that it manages for 

4746 jobs that are eligible for execution. The algorithm by which the batch server selects eligible jobs 

4747 for execution is implementation-dependent. 

4748 As part of creating the process for the batch job, the batch server opens the standard output and 

4749 standard error streams of the session. 

4750 The attributes of a batch job may indicate that the batch server that executes the job is to send 

4751 mail to a list of users at the time it begins execution of the job. 
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4752 3.1.7 Batch Job Exit 

4753 When the session leader of an executing job terminates, the job exits. As part of exiting a batch 

4754 job, the batch server that manages the job shall remove the job from the batch queue in which it 

4755 resides. The server shall transfer output files of the job to a location described by the attributes of 

4756 the job. 

4757 The attributes of a batch job may indicate that the batch server that manages the job should send 

4758 mail to a list of users at the time the job exits. 

4759 3.1.8 Batch Job Abort 

4760 A batch server aborts jobs for which a required deferred service cannot be performed. The 

4761 attributes of a batch job may indicate that the batch server that aborts the job shall send mail to a 

4762 list of users at the time it aborts the job. 

4763 3.1.9 Batch Job States 

4764 A batch job is always in one of several states: QUEUED, RUNNING, HELD, WAITING, 

4765 EXITING, or TRANSITING. The state of a batch job determines the types of requests that the 

4766 batch server that manages the job can accept for the job. A batch server changes the state of a 

4767 batch job either in response to service requests from clients or as a result of deferred services 

4768 such as job execution or job routing. 

4769 A batch job that is in the QUEUED state resides in a batch queue, but is still pending either 

4770 execution or routing, depending on the batch queue type. 

4771 A batch job that resides in an execution queue and is executing is defined to be in the RUNNING 

4772 state. While a batch job is in the RUNNING state, a session leader is associated with the job. 

4773 A batch job that resides in an execution queue, but is ineligible to run because of a hold attribute, 

4774 is defined to be in the HELD state. A batch job that is not held, but which must wait until a 

4775 future date and time before executing, is defined to be in the WAITING state. 

4776 A batch job for which the session leader has terminated is defined to be in the EXITING state, 

4777 and the batch server that manages such a batch job cannot accept job modification requests that 

4778 affect the job. While a batch job is in the EXITING state, the batch server that manages the job is 

4779 staging output files and notifying clients of job completion. Once a batch job has exited, it no 

4780 longer exists as an object managed by a batch server. 

4781 A batch job that is being moved from a routing queue to another queue is defined to be in the 

4782 TRANSITING state. 

4783 3.1.10 Batch Authorization 

4784 In order to access batch services, a user must have execute access to a batch client. For example, 

4785 to use the command language interface defined in this section, the user must be able to execute 

4786 the programs that embody those utilities. 

4787 Clients, such as the utilities in this section, access batch services by means of requests to one or 

4788 more batch servers. To acquire the services of any given batch server, the user identifier under 

4789 which the client runs must be authorized to use that batch server. 

4790 The user with an associated user name that creates a batch job owns the job and can perform 

4791 actions such as read, modify, delete, and move. 

4792 A user identifier of the same value at a different host need not be the same user. For example, 

4793 user name smith at host alpha may or may not represent the same person as user name smith at 
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4794 host beta. Likewise, the same person may have access to different user names on different hosts. I 

4795 An implementation may optionally provide an authorization mechanism that permits one user I 

4796 name to access jobs under another user name. I 

4797 A process on a client host may be authorized to run processes under multiple user names at a I 

4798 batch server host. Where appropriate, the utilities defined in this volume of I 

4799 IEEE Std. 1003.1-200x provide a means for a user to choose from among such user names when I 

4800 creating or modifying a batch job. I 

4801 3.1.11 Batch Administration I 

4802 The processing of a batch job by a batch server is affected by the attributes of the job. The I 

4803 processing of a batch job may also be affected by the attributes of the batch queue in which the I 

4804 job resides and by the status of the batch server that manages the job. I 

4805 A batch administrator is a user that is authorized to modify all the attributes of queues and jobs I 

4806 and to change the status of a batch server. A batch operator is a user that is authorized to modify I 

4807 some, but not all, of the attributes of jobs and queues, and may change the status of the batch I 

4808 server. I 

4809 3.1.12 Batch Notification I 

4810 Whereas batch servers are persistent entities, clients are often transient. For example, the qsub I 

4811 utility creates a batch job and exits. For this reason, batch servers notify users of batch job events I 

4812 by sending mail to the user that owns the job, or to other designated users. I 

4813 3.2 Batch Services l 

4814 The presence of Batch Environment option services is indicated by the configuration variable I 

4815 POSIX2_PBS. A conforming batch server provides services as defined in this section. I 

4816 A batch server provides batch services in two ways: I 

4817 1. The batch server provides a service at the request of a client. I 

4818 2. The batch server provides a deferred service as a result of a change in conditions I 

4819 monitored by the batch server. I 

4820 If a batch server cannot complete a request, it rejects the request. If a batch server cannot I 

4821 complete a deferred service for a batch job, the batch server aborts the batch job. Table 3-2 is a I 

4822 summary of environment variables that shall be supported by an implementation of the batch I 

4823 server and utilities. I 

4824 Table 3-2 Environment Variable Summary I 
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4825 


_ 1 

4826 

Variable 

Description 

1 

4827 

PBS_DPREFIX 

Defines the directive prefix (see qsub) 


4828 

PBS_ENVIRONMENT 

Batch Job is batch or interactive (see Section 3.2.2.1 on page 139) 


4829 

PBSJOBID 

Job_identifier attribute of job (see Section 3.2.3.8 on page 151) 


4830 

PBSJOBNAME 

Job_name attribute of job (see Section 3.2.3.8 on page 151) 


4831 

PBS_0_HOME 

Defines the HOME of the batch client (see qsub) 


4832 

PBS_0_HOST 

Defines the host name of the batch client (see qsub) 


4833 

PBS_0_LANG 

Defines the LANG of the batch client (see qsub) 


4834 

PBS_0_LOGNAME 

Defines the LOGNAME of the batch client (see qsub) 


4835 

PBS_0_MAIL 

Defines the MAIL of the batch client (see qsub) 


4836 

PBS_0_PATH 

Defines the PATH of the batch client (see qsub) 


4837 

PBS_0_QUEUE 

Defines the submit queue of the batch client (see qsub) 


4838 

PBS_0_SHELL 

Defines the SHELL of the batch client (see qsub) 


4839 

PBS_0_TZ 

Defines the TZ of the batch client (see qsub) 


4840 

PBS_0_W ORKDIR 

Defines the working directory of the batch client (see qsub) 


4841 

PBS_QUEUE 

Defines the initial execution queue (see Section 3.2.2.1 on page 


4842 


139) 



4843 3.2.1 Batch Job States 

4844 A batch job is always in one of several states: QUEUED, RUNNING, HELD, WAITING, 

4845 EXITING, or TRANSITING. The state of a batch job determines the types of requests that the 

4846 batch server that manages the batch job can accept for the batch job. A batch server changes the 

4847 state of a batch job either in response to service requests from clients or as a result of deferred 

4848 services, such as job execution or job routing. 

4849 A batch job that is in the QUEUED state resides in a queue but is still pending either execution or 

4850 routing, depending on the queue type. 

4851 A batch server that queues a batch job in a routing queue shall put the batch job in the QUEUED 

4852 state. A batch server that puts a batch job in an execution queue, but has not yet executed the 

4853 batch job, shall put the batch job in the QUEUED state. A batch job that resides in an execution 

4854 queue and is executing is defined to be in the RUNNING state. While a batch job is in the 

4855 RUNNING state, a session leader is associated with the batch job. 

4856 A batch job that resides in an execution queue, but is ineligible to run because of a hold attribute, 

4857 is defined to be in the HELD state. 

4858 A batch job that is not held, but must wait until a future date and time before executing, is 

4859 defined to be in the WAITING state. 

4860 When the session leader associated with a running job exits, the batch job shall be placed in the 

4861 EXITING state. 

4862 A batch job for which the session leader has terminated is defined to be in the EXITING state, 

4863 and the batch server that manages such a batch job cannot accept job modification requests that 

4864 affect the batch job. While a batch job is in the EXITING state, the batch server that manages the 

4865 batch job is staging output files and notifying clients of job completion. Once a batch job has 

4866 exited, it no longer exists as an object managed by a batch server. 

4867 A batch job that is being moved from a routing queue to another queue is defined to be in the 

4868 TRANSITING state. 
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4869 When a batch job in a routing queue has been selected to be moved to a new destination, then 

4870 the batch job is in either the QUEUED state or the TRANSITING state, depending on the batch 

4871 server implementation. 

4872 Batch jobs with either a Execution_Time attribute value set in the future or a HoldJTypes attribute 

4873 of value not equal to NO_HOLD, or both, may be routed or held in the routing queue. An 

4874 implementation shall document the treatment of jobs with the ExecutionJTime or Hold_Types 

4875 attributes in a routing queue. 

4876 When a batch job in a routing queue has not been selected to be moved to a new destination and 

4877 the batch job has a Hold_Types attribute value of other than NO_HOLD, then the job should be in 

4878 the HELD state. 

4879 Note: The effect of a hold upon a batch job in a routing queue is implementation- 

4880 dependent. The implementation should use the state that matches whether the batch 

4881 job can route with a hold or not. 

4882 When a batch job in a routing queue has not been selected to be moved to a new destination and 

4883 the batch job has: 

4884 • A Hold_Types attribute value of NO_HOLD 

4885 • An Execution JTime attribute in the past 

4886 then the batch job shall be in the QUEUED state. 

4887 When a batch job in a routing queue has not been selected to be moved to a new destination and 

4888 the batch job has: 

4889 • A HoldJTypes attribute value of NO_HOLD 

4890 • A Execution JTime attribute in the future 

4891 then the batch job may be in the WAITING state. 

4892 Note: The effect of a future execution time upon a batch job in a routing queue is 

4893 implementation-dependent. The implementation should use the state that matches 

4894 whether the batch job can route with a hold or not. 

4895 Table 3-3 on page 140 describes the next state of a batch job, given the current state of the batch 

4896 job and the type of request. Table 3-4 on page 141 describes the response of a batch server to a 

4897 request, given the current state of the batch job and the type of request. 

4898 3.2.2 Deferred Batch Services 

4899 This section describes the deferred services performed by batch servers: job execution, job 

4900 routing, job exit, job abort, and the rerunning of jobs after a restart. 

4901 3.2.2.1 Batch Job Execution 

4902 To execute a batch job is to create a session leader (a process) that runs the shell program 

4903 indicated by the Shell_Path_List attribute of the batch job. The script is passed to the program as 

4904 its standard input. An implementation of the batch server may pass the script to the program by 

4905 other means. The implementation shall document the alternate means in the conformance 

4906 document. At the time a batch job begins execution, it is defined to enter the RUNNING state. 
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4907 Table 3-3 Next State Table 


4908 


Current State 

4909 

Request Type 

X 

Q 

R 

H 

W 

E 

T 

4910 

Queue Batch Job Request 

Q 

e 

e 

e 

e 

e 

e 

4911 

Modify Batch Job Request 

e 

Q 

R 

H 

W 

e 

T 

4912 

Delete Batch Job Request 

e 

X 

E 

X 

X 

E 

X 

4913 

Batch Job Message Request 

e 

Q 

R 

H 

w 

E 

T 

4914 

Rerun Batch Job Request 

e 

e 

Q 

e 

e 

e 

e 

4915 

Signal Batch Job Request 

e 

e 

R 

H 

W 

e 

e 

4916 

Batch Job Status Request 

e 

Q 

R 

H 

w 

E 

T 

4917 

Batch Queue Status Request 

X 

Q 

R 

H 

w 

E 

T 

4918 

Server Status Request 

X 

Q 

R 

H 

w 

E 

T 

4919 

Select Batch Jobs Request 

X 

Q 

R 

H 

w 

E 

T 

4920 

Move Batch Job Request 

e 

Q 

R 

H 

w 

e 

T 

4921 

Hold Batch Job Request 

e 

H 

R/H 

H 

H 

e 

T 

4922 

Release Batch Job Request 

Q 

R 

Q/W/H 

W 

e 

T 


4923 

Server Shutdown Request 

X 

Q 

Q 

H 

W 

E 

T 

4924 

Locate Batch Job Request 

e 

Q 

R 

H 

W 

E 

T 


4925 Legend 

4926 X Nonexistent 

4927 Q QUEUED 

4928 R RUNNING 

4929 H HELD 

4930 W WAITING 

4931 E EXITING 

4932 T TRANSITING 

4933 e Error 

4934 A batch server that has an execution queue containing jobs is said to own the queue and manage 

4935 the batch jobs in that queue. A batch server that has been started shall execute the batch jobs in 

4936 the execution queues owned by the batch server. The batch server shall schedule for execution 

4937 those jobs in the execution queues that are in the QUEUED state. The algorithm for scheduling 

4938 jobs is implementation-dependent. 

4939 A batch server that executes a batch job shall create, in the environment of the session leader of 

4940 the batch job, an environment variable named PBS_ENVIRONMENT, the value of which is the 

4941 string PBS_BATCH encoded in the portable character set. 

4942 A batch server that executes a batch job shall create, in the environment of the session leader of 

4943 the batch job, an environment variable named PBS_QUEUE, the value of which is the name of 

4944 the execution queue of the batch job encoded in the portable character set. 

4945 To rerun a batch job is to requeue a batch job that is currently executing and then kill the session 

4946 leader of the executing job by sending a SIGKILL prior to completion; see Section 3.2.3.11 on 

4947 P a g e 153. A batch server that reruns a batch job shall append the standard output and standard 

4948 error files of the batch job to the corresponding files of the previous execution, if they exist, with 

4949 appropriate annotation. If either file does not exist, that file shall be created as in normal 

4950 execution. 
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4951 Table 3-4 Results/Output Table 


4952 


Current State 

4953 

Request Type 

X 

Q 

R 

H 

W 

E 

T 

4954 

Queue Batch Job Request 

o 

e 

e 

e 

e 

e 

e 

4955 

Modify Batch Job Request 

e 

O 

e 

O 

O 

e 

e 

4956 

Delete Batch Job Request 

e 

O 

O 

O 

O 

e 

O 

4957 

Batch Job Message Request 

e 

e 

O 

e 

e 

e 

e 

4958 

Rerun Batch Job Request 

e 

e 

O 

e 

e 

e 

e 

4959 

Signal Batch Job Request 

e 

e 

O 

e 

e 

e 

e 

4960 

Batch Job Status Request 

e 

O 

O 

O 

O 

O 

O 

4961 

Batch Queue Status Request 

O 

O 

O 

O 

O 

O 

O 

4962 

Server Status Request 

O 

O 

O 

O 

O 

O 

O 

4963 

Select Batch Job Request 

e 

O 

O 

O 

O 

O 

O 

4964 

Move Batch Job Request 

e 

O 

O 

O 

O 

e 

e 

4965 

Hold Batch Job Request 

e 

O 

O 

O 

O 

e 

e 

4966 

Release Batch Job Request 

e 

O 

e 

O 

O 

e 

e 

4967 

Server Shutdown Request 

O 

O 

e 

O 

O 

e 

e 

4968 

Locate Batch Job Request 

e 

O 

O 

O 

O 

O 

O 


4969 Legend 

4970 O OK 

4971 e Error message 

4972 The execution of a batch job by a batch server is controlled by job, queue, and server attributes, 

4973 as defined in this section. 

4974 Account_Name Attribute 

4975 Batch accounting is an optional feature of batch servers. If a batch server implements 

4976 accounting, the statements in this section apply and the configuration variable 

4977 POSIX2_PBS_ACCOUNTING shall be set to 1. 

4978 A batch server that executes a batch job shall charge the account named in the Acconnt_Name 

4979 attribute of the batch job for resources consumed by the batch job. 

4980 If the Account_Name attribute of the batch job is absent from the batch job attribute list or is 

4981 altered while the batch job is in execution, the batch server action is implementation-dependent. 

4982 Checkpoint Attribute 

4983 Batch checkpointing is an optional feature of batch servers. If a batch server implements 

4984 checkpointing, the statements in this section apply and the configuration variable 

4985 POSIX2_PBS_CHECKPOINT shall be set to 1. 

4986 There are two attributes associated with the checkpointing feature: Checkpoint and 

4987 MinimumjCpu_tnterval. Checkpoint is a batch job attribute, while MinimiimjCpuJnterval is a 

4988 queue attribute. An implementation that does not support checkpointing shall support the 

4989 Checkpoint job attribute to the extent that the batch server shall maintain and pass this attribute 

4990 to other servers. 

4991 The behavior of a batch server that executes a batch job for which the value of the Checkpoint 

4992 attribute is CHECKPOINT_UNSPECIFIED is implementation-dependent. The implementation 

4993 shall document the behavior of the batch server. A batch server that executes a batch job for 
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4994 which the value of the Checkpoint attribute is NO_CHECKPOINT shall not checkpoint the batch 

4995 job. 

4996 A batch server that executes a batch job for which the value of the Checkpoint attribute is 

4997 CHECKPOINT_AT_SHUTDOWN shall checkpoint the batch job only when the batch server 

4998 accepts a request to shut down during the time when the batch job is in the RUNNING state. 

4999 A batch server that executes a batch job for which the value of the Checkpoint attribute is 

5000 CHECKPOINT_AT_MIN_CPU_INTERVAL shall checkpoint the batch job at the interval 

5001 specified by the Minimum_Cpu_Interval attribute of the queue for which the batch job has been 

5002 selected. The Minimum_Cpu_lnterval attribute shall be specified in units of CPU minutes. 

5003 A batch server that executes a batch job for which the value of the Checkpoint attribute is an 

5004 unsigned integer shall checkpoint the batch job at an interval that is the value of either the 

5005 Checkpoint attribute, or the Minimum_Cpu_lnterval attribute of the queue for which the batch job 

5006 has been selected, whichever is greater. Both intervals shall be in units of CPU minutes. When 

5007 the Minimum_Cpu_lnterval attribute is greater than the Checkpoint attribute, the batch job shall 

5008 write a warning message to the standard error stream of the batch job. 

5009 Error_Path Attribute 

5010 The Error_Path attribute of a running job cannot be changed by a Modify Batch Job Request. When 

5011 the Join_Path attribute of the batch job is set to the value FALSE and the Keep_Files attribute of 

5012 the batch job does not contain the value KEEP_STD_ERROR, a batch server that executes a batch 

5013 job shall perform one of the following actions: 

5014 • Set the standard error stream of the session leader of the batch job to the path described by 

5015 the value of the Error_Path attribute of the batch job. 

5016 • Buffer the standard error of the session leader of the batch job until completion of the batch 

5017 job, and when the batch job exits return the contents to the destination described by the value 

5018 of the Error_Path attribute of the batch job. Where the batch server buffers standard error is 

5019 implementation-dependent. 

5020 Applications shall not rely on having access to the standard error of a batch job prior to the 

5021 completion of the batch job. 

5022 When the Error_Path attribute does not specify a host name, then the batch server shall retain the 

5023 standard error of the batch job on the host of execution. 

5024 When the Error_Path attribute does specify a host name and the Keep_Files attribute does not 

5025 contain the value KEEP_STD_ERROR, then the final destination of the standard error of the 

5026 batch job shall be on the host whose host name is specified. 

5027 If the path indicated by the value of the Error_Path attribute of the batch job is a relative path, the 

5028 batch server shall expand the path relative to the home directory of the user on the host to which 

5029 the file is being returned. 

5030 When the batch server buffers the standard error of the batch job and the file cannot be opened 

5031 for write upon completion of the batch job, then the server shall place the standard error in an 

5032 implementation-dependent location and notify the user of the location via mail. It shall be 

5033 possible for the user to process this mail using the mailx utility. 

5034 If a batch server that does not buffer the standard error cannot open the standard error path of 

5035 the batch job for write access, then the batch server shall abort the batch job. 
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5036 Execution_Time Attribute 

5037 A batch server shall not execute a batch job before the time represented by the value of the 

5038 Execution_Time attribute of the batch job. The Execution JTime attribute is defined in seconds since 

5039 the Epoch. 

5040 Hold_Types Attribute 

5041 A batch server shall support the following hold types: 

5042 s Can be set or released by a user with at least a privilege level of batch administrator 

5043 (SYSTEM). 

5044 o Can be set or released by a user with at least a privilege level of batch operator 

5045 (OPERATOR). 

5046 u Can be set or released by the user with at least a privilege level of user, where the user is 

5047 defined in the JobjOwner attribute (USER). 

5048 n Indicates that none of the Hold_Types attributes are set (NO_HOLD). 

5049 An implementation may define other hold types. The conformance document for an 

5050 implementation shall describe any additional hold types, how they are specified, their internal 

5051 representation, their behavior, and how they affect the behavior of other utilities. 

5052 The value of the Hold_Types attribute shall be the union of the valid hold types (ss, oo, uu, and 

5053 any implementation-dependent hold types), or nn. 

5054 A batch server shall not execute a batch job if the Hold_Types attribute of the batch job has a 

5055 value other than NO_HOLD. If the Hold_Types attribute of the batch job has a value other than 

5056 NO_HOLD, the batch job shall be in the HELD state. 

5057 Job_Owner Attribute 

5058 The Job_Owner attribute consists of a pair of user name and host name values of the form: 

5059 username@hostname 

5060 A batch server that accepts a Queue Batch Job Request shall set the JobjOwner attribute to a string 

5061 that is the username@hostname of the user who submitted the job. 

5062 Join_Path Attribute 

5063 A batch server that executes a batch job for which the value of the Join_Path attribute is TRUE 

5064 shall ignore the value of the Error_Path attribute and merge the standard error of the batch job 

5065 with the standard output of the batch job. 

5066 Keep_Files Attribute 

5067 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 

5068 the value KEEP_STD_OUTPUT shall retain the standard output of the batch job on the host 

5069 where execution occurs. The standard output shall be retained in the home directory of the user 

5070 under whose user ID the batch job is executed and the file name shall be the default file name for 

5071 the standard output as defined under the -o option of the qsub utility. The Output_Path attribute 

5072 is not modified. 

5073 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 

5074 the value KEEP_STD_ERROR shall retain the standard error of the batch job on the host where 

5075 execution occurs. The standard error shall be retained in the home directory of the user under 

5076 whose user ID the batch job is executed and the file name shall be the default file name for 
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5077 standard error as defined under the -e option of the qsub utility. The Error_Path attribute is not 

5078 modified. 

5079 A batch server that executes a batch job for which the value of the Keep_Files attribute includes 

5080 values other than KEEP_STD_OUTPUT and KEEP_STD_ERROR shall retain these other files on 

5081 the host where execution occurs. These files shall be retained in the home directory of the user 

5082 under whose user identifier the batch job is executed and the file names shall be the default file 

5083 names for the files as defined in the conformance document for the implementation. 

5084 Mail_Points and Mail_Users Attributes 

5085 A batch server that executes a batch job for which one of the values of the Mail_Points attribute is 

5086 the value MAIL_AT_BEGINNING shall send a mail message to each user account listed in the 

5087 Mail_Users attribute of the batch job. 

5088 The mail message shall contain at least the batch job identifier, queue, and server at which the 

5089 batch job currently resides, and the JobjOwner attribute. 

5090 Output_Path Attribute 

5091 The Output_Path attribute of a running job cannot be changed by a Modify Batch Job Request. 

5092 When the Keep_Files attribute of the batch job does not contain the value KEEP_STD_OUTPUT, a 

5093 batch server that executes a batch job shall either: 

5094 • Set the standard output stream of the session leader of the batch job to the destination 

5095 described by the value of the Output_Path attribute of the batch job. 

5096 or: 

5097 • Buffer the standard output of the session leader of the batch job until completion of the batch 

5098 job, and when the batch job exits return the contents to the destination described by the value 

5099 of the Output_Path attribute of the batch job. 

5100 When the Output_Path attribute does not specify a host name, then the batch server shall retain 

5101 the standard output of the batch job on the host of execution. 

5102 When the Keep_Files attribute does not contain the value KEEP_STD_OUTPUT and the 

5103 Output_Path attribute does specify a host name, then the final destination of the standard output 

5104 of the batch job shall be on the host specified. 

5105 If the path specified in the Output_Path attribute of the batch job is a relative path, the batch 

5106 server shall expand the path relative to the home directory of the user on the host to which the 

5107 file is being returned. 

5108 Whether or not the batch server buffers the standard output of the batch job until completion of 

5109 the batch job is implementation-dependent. Applications shall not rely on having access to the 

5110 standard output of a batch job prior to the completion of the batch job. 

5111 When the batch server does buffer the standard output of the batch job and the file cannot be 

5112 opened for write upon completion of the batch job, then the batch server shall place the standard 

5113 output in an implementation-dependent location and notify the user of the location via mail. It 

5114 shall be possible for the user to process this mail using the mailx utility. 

5115 If a batch server that does not buffer the standard output cannot open the standard output path 

5116 of the batch job for write access, then the batch server shall abort the batch job. 
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5117 Priority Attribute 

5118 A batch server implementation might choose to preferentially execute a batch job based on the 

5119 Priority attribute. The interpretation of the batch job Priority attribute by a batch server is 

5120 implementation-dependent. If an implementation uses the Priority attribute, it shall interpret 

5121 larger values of the Priority attribute to mean the batch job shall be preferentially selected for 

5122 execution. 

5123 Rerunable Attribute 

5124 A batch job that began execution but did not complete, because the batch server either shut 

5125 down or terminated abnormally, shall be requeued if the Rerunable attribute of the batch job has 

5126 the value TRUE. 

5127 If a batch job, which was requeued after beginning execution but prior to completion, has a valid 

5128 checkpoint file and the batch server supports checkpointing, then the batch job shall be restarted 

5129 from the last valid checkpoint. 

5130 If the batch job cannot be restarted from a checkpoint, then when a batch job has a Rerunable 

5131 attribute value of TRUE and was requeued after beginning execution but prior to completion, 

5132 the batch server shall place the batch job into execution at the beginning of the job. 

5133 When a batch job has a Rerunable attribute value other than TRUE and was requeued after 

5134 beginning execution but prior to completion, and the batch job cannot be restarted from a 

5135 checkpoint, then the batch server shall abort the batch job. 

5136 Resource_List Attribute 

5137 A batch server that executes a batch job shall establish the resource limits of the session leader of 

5138 the batch job according to the values of the Resonrce_List attribute of the batch job. Resource 

5139 limits shall be enforced by an implementation-dependent method. 

5140 Shell_Path_List Attribute 

5141 The Shell_Path_List job attribute consists of a list of pairs of path name and host name values. 

5142 The host name component can be omitted, in which case the path name serves as the default 

5143 path name when a batch server cannot find the name of the host on which it is running in the 

5144 list. 

5145 A batch server that executes a batch job shall select, from the value of the Shell_Path_List 

5146 attribute of the batch job, a path name where the shell to execute the batch job shall be found. 

5147 The batch server shall select the path name, in order of preference, according to the following 

5148 methods: 

5149 • Select the path name that contains the name of the host on which the batch server is running. 

5150 • Select the path name for which the host name has been omitted. 

5151 • Select the path name for the login shell of the user under which the batch job is to execute. 

5152 If the shell path value selected is an invalid path name, the batch server shall abort the batch job. 

5153 If the value of the selected path name from the Shell_Path_List attribute of the batch job 

5154 represents a partial path, the batch server shall expand the path relative to a path that is 

5155 implementation-dependent. 

5156 The batch server that executes the batch job shall execute the program that was selected from the 

5157 Shell_Path_List attribute of the batch job. The batch server shall pass the path to the script of the 

5158 batch job as the first argument to the shell program. 
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5159 User_List Attribute 

5160 The User_List job attribute consists of a list of pairs of user name and host name values. The host 

5161 name component can be omitted, in which case the user name serves as a default when a batch 

5162 server cannot find the name of the host on which it is running in the list. 

5163 A batch server that executes a batch job shall select, from the value of the User_List attribute of 

5164 the batch job, a user name under which to create the session leader. The server shall select the 

5165 user name, in order of preference, according to the following methods: 

5166 • Select the user name of a value that contains the name of the host on which the batch server 

5167 executes. 

5168 • Select the user name of a value for which the host name has been omitted. 

5169 • Select the user name from the JobjOwner attribute of the batch job. 

5170 Variable_List Attribute 

5171 A batch server that executes a batch job shall create, in the environment of the session leader of 

5172 the batch job, each environment variable listed in the Variable_List attribute of the batch job, and 

5173 set the value of each such environment variable to that of the corresponding variable in the 

5174 variable list. 

5175 3.2.22 Batch Job Routing 

5176 To route a batch job is to select a queue from a list and move the batch job to that queue. 

5177 A batch server that has routing queues, which have been started, shall route the jobs in the 

5178 routing queues owned by the batch server. A batch server is allowed to delay the routing of a 

5179 batch job. The algorithm for selecting a batch job and the queue to which it will be routed is 

5180 implementation-dependent. 

5181 When a routing queue has multiple possible destinations specified, then the precedence of the 

5182 destination is implementation-dependent. 

5183 A batch server that routes a batch job to a queue at another server shall move the batch job into 

5184 the target queue with a Queue Batch Job Request. 

5185 If the target server rejects the Queue Batch Job Request, the routing server shall retry routing the 

5186 batch job or abort the batch job. A batch server that retries failed routings shall provide a means 

5187 for the batch administrator to specify the number of retries and the minimum period of time 

5188 between retries. The means by which an administrator specifies the number of retries and the 

5189 delay between retries is implementation-dependent. When the number of retries specified by the 

5190 batch administrator has been exhausted, the batch server shall abort the batch job and perform 

5191 the functions of Batch Job Exit ; see Section 3.2.2.3. 

5192 3.2.2.3 Batch Job Exit 

5193 For each job in the EXITING state, the batch server that exited the batch job shall perform the 

5194 following deferred services in the order specified: 

5195 1. If buffering standard error, move that file into the location specified by the Error_Path 

5196 attribute of the batch job. 

5197 2. If buffering standard output, move that file into the location specified by the Output_Path 

5198 attribute of the batch job. 

5199 3. If the Mail_Points attribute of the batch job includes MAIL_AT_EXIT, send mail to the users 

5200 listed in the Mail_Users attribute of the batch job. The mail message shall contain at least 
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5201 the batch job identifier, queue, and server at which the batch job currently resides, and the 

5202 Job_Owner attribute. 

5203 4. Remove the batch job from the queue. 

5204 If a batch server that buffers the standard error output cannot return the standard error file to 

5205 the standard error path at the time the batch job exits, the batch server shall do one of the 

5206 following: 

5207 • Mail the standard error file to the batch job owner. 

5208 • Save the standard error file and mail the location and name of the file where the standard 

5209 error is stored to the batch job owner. 

5210 • Save the standard error file and notify the user by other means, in which case the 

5211 conformance document for the implementation shall document the method of notification. 

5212 If a batch server that buffers the standard output cannot return the standard output file to the 

5213 standard output path at the time the batch job exits, the batch server shall do one of the 

5214 following: 

5215 • Mail the standard output file to the batch job owner. 

5216 • Save the standard output file and mail the location and name of the file where the standard 

5217 output is stored to the batch job owner. 

5218 • Save the standard output file and notify the user by other means, in which case the 

5219 conformance document for the implementation shall document the method of notification. 

5220 At the conclusion of job exit processing, the batch job is no longer managed by a batch server. 

5221 3.2.2.4 Batch Server Restart 

5222 A batch server that has been either shutdown or terminated abnormally, and has returned to 

5223 operation, is said to have restarted. 

5224 Upon restarting, a batch server shall requeue those jobs managed by the batch server that were 

5225 in the RUNNING state at the time the batch server shut down and for which the Reriinable 

5226 attribute of the batch job has the value TRUE. 

5227 Queues are defined to be non-volatile. A batch server shall store the content of queues that it 

5228 controls in such a way that server and system shutdowns do not erase the content of the queues. 

5229 3.2.2.5 Batch Job Abort 

5230 A batch server that cannot perform a deferred service for a batch job shall abort the batch job. 

5231 A batch server that aborts a batch job shall perform the following services: 

5232 • Delete the batch job from the queue in which it resides. 

5233 • If the Mail_Points attribute of the batch job includes the value MAIL_AT_ABORT, send mail 

5234 to the users listed in the value of the Mail_Users attribute of the job. The mail message shall 

5235 contain at least the batch job identifier, queue, and server at which the batch job currently 

5236 resides, the JobjOwner attribute, and the reason for the abort. 

5237 • If the batch job was in the RUNNING state, terminate the session leader of the executing job 

5238 by sending the session leader a SIGKILL, place the batch job in the EXITING state, and 

5239 perform the services of Batch Job Exit. 
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5240 3.2.3 Requested Batch Services 

5241 This section describes the services provided by batch servers in response to requests from 

5242 clients. Table 3-5 summarizes the current set of batch service requests and for each gives its type 

5243 (deferred or not) and whether it is an optional function. 

5244 If a request is rejected because the batch client is not authorized to perform the action, the batch 

5245 server shall return the same status as when the batch job does not exist. 

5246 3.2.3.1 Delete Batch Job Request 

5247 A batch job is defined to have been deleted when it has been removed from the queue in which it 

5248 resides and not instantiated in another queue. A client requests that the server that manages a 

5249 batch job delete the batch job. Such a request is called a Delete Batch Job Request. 


5250 Table 3-5 Batch Services Summary 


5251 

Batch Service 

Deferred 

Optional 

5252 

Batch Job Execution 

Yes 

No 

5253 

Batch Job Routing 

Yes 

No 

5254 

Batch Job Exit 

Yes 

No 

5255 

Batch Server Restart 

Yes 

No 

5256 

Batch Job Abort 

Yes 

No 

5257 

Queue Batch Job Request 

No 

No 

5258 

Modify Batch Job Request 

No 

No 

5259 

Delete Batch Job Request 

No 

No 

5260 

Batch Job Message Request 

No 

Yes 

5261 

Rerun Batch Job Request 

No 

No 

5262 

Signal Batch Job Request 

No 

No 

5263 

Batch Job Status Request 

No 

No 

5264 

Batch Queue Status Request 

No 

No 

5265 

Server Status Request 

No 

No 

5266 

Select Batch Jobs Request 

No 

No 

5267 

Move Batch Job Request 

No 

No 

5268 

Hold Batch Job Request 

No 

No 

5269 

Release Batch Job Request 

No 

No 

5270 

Server Shutdown Request 

No 

No 

5271 

Locate Batch Job Request 

No 

Yes 

5272 

Track Batch Job Request 

No 

Yes 


5273 A batch server shall reject a Delete Batch Job Request if any of the following statements are true: 

5274 • The user of the batch client is not authorized to delete the designated job. 

5275 • The designated job is not managed by the batch server. 

5276 • The designated job is in a state inconsistent with the delete request. 

5277 A batch server may reject a Delete Batch Job Request for other reasons. The conformance document 

5278 for an implementation shall describe the reasons for which a Delete Batch Job Request may be 

5279 rejected. The conformance document for an implementation shall describe the method used to 

5280 determine whether the user of a client is authorized to perform the requested action. 

5281 A batch server requested to delete a batch job shall delete the batch job if the batch job exists and 

5282 is not in the EXITING state. 
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5283 A batch server that deletes a batch job in the RUNNING state shall send a SIGKILL signal to the 

5284 session leader of the batch job. A batch server may send additional signals to the session leader 

5285 of the job prior to sending the SIGKILL signal. The conformance document for such a batch 

5286 server shall document the signals that are sent to the session leader. 

5287 A batch server that deletes a batch job in the RUNNING state shall place the batch job in the 

5288 EXITING state after it has killed the session leader of the batch job and shall perform the services 

5289 of batch job exit. 

5290 3.23.2 Hold Batch Job Request 

5291 A batch client can request that the batch server add one or more holds to a batch job. Such a 

5292 request is called a Hold Batch Job Request. 

5293 A batch server shall reject a Hold Batch Job Request if any of the following statements are true: 

5294 • The batch server does not support one or more of the requested holds to be added to the 

5295 batch job. 

5296 • The user of the batch client is not authorized to add one or more of the requested holds to the 

5297 batch job. 

5298 • The batch server does not manage the specified job. 

5299 • The designated job is in the EXITING state. 

5300 A batch server may reject a Hold Batch Job Request for other reasons. The conformance document 

5301 for an implementation shall document the reasons for which a Hold Batch Job Request may be 

5302 rejected. The conformance document for an implementation shall describe the method used to 

5303 determine whether the user of a client is authorized to perform the requested action. 

5304 A batch server that accepts a Hold Batch Job Request for a batch job in the RUNNING state shall 

5305 place a hold on the batch job. The conformance document shall describe what effect, if any, the 

5306 hold will have on a batch job in the RUNNING state. 

5307 A batch server that accepts a Hold Batch Job Request shall add each type of hold listed in the Hold 

5308 Batch Job Request, that is not already present, to the value of the Hold_Types attribute of the batch 

5309 job. 

5310 3.2.33 Batch Job Message Request 

5311 Batch Job Message Request is an optional feature of batch servers. If an implementation supports 

5312 Batch Job Message Request, the statements in this section apply and the configuration variable 

5313 POSIX2_PBS_MESSAGE shall be set to 1. 

5314 A batch client can request that a batch server write a message into certain output files of a batch 

5315 job. Such a request is called a Batch Job Message Request. 

5316 A batch server shall reject a Batch Job Message Request if any of the following statements are true: 

5317 • The batch server does not support sending messages to jobs. 

5318 • The user of the batch client is not authorized to post a message to the designated job. 

5319 • The designated job does not exist on the batch server. 

5320 • The designated job is not in the RUNNING state. 

5321 A batch server may reject a Batch Job Message Request for other reasons. The conformance 

5322 document for an implementation shall describe the reasons for which a Batch Job Message Request 

5323 may be rejected. The conformance document for an implementation shall describe the method 
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5324 used to determine whether the user of a client is authorized to perform the requested action. 

5325 A batch server that accepts a Batch Job Message Request shall write the message sent by the batch 

5326 client into the files indicated by the batch client. 

5327 3.23.4 Batch Job Status Request 

5328 A batch client can request that a batch server respond with the status and attributes of a batch 

5329 job. Such a request is called a Batch Job Status Request. 

5330 A batch server shall reject a Batch Job Status Request if any of the following statements are true: 

5331 • The user of the batch client is not authorized to query the status of the designated job. 

5332 • The designated job is not managed by the batch server. 

5333 A batch server may reject a Batch Job Status Request for other reasons. The conformance 

5334 document for an implementation shall describe the reasons for which a Batch Job Status Request 

5335 may be rejected. The conformance document for an implementation shall describe the method 

5336 used to determine whether the user of a client is authorized to perform the requested action. 

5337 A batch server that accepts a Batch Job Status Request shall return a Batch Job Status Message to the 

5338 batch client. 

5339 A batch server may return other information in response to a Batch Job Status Request. 

5340 3.23.5 Locate Batch Job Request 

5341 Locate Batch Job Request is an optional feature of batch servers. If an implementation supports 

5342 Locate Batch Job Request, the statements in this section apply and the configuration variable 

5343 POSIX2_PBS_LOCATE shall be set to 1. 

5344 A batch client can ask a batch server to respond with the location of a batch job that was created 

5345 by the batch server. Such a request is called a Locate Batch Job Request. 

5346 A batch server that accepts a Locate Batch Job Request shall return a Batch Job Location Message to 

5347 the batch client. 

5348 A batch server may reject a Locate Batch Job Request for a batch job that was not created by that 

5349 server. 

5350 A batch server may reject a Locate Batch Job Request for a batch job that is no longer managed by 

5351 that server; that is, for a batch job that is not in a queue owned by that server. 

5352 A batch server may reject a Locate Batch Job Request for other reasons. The conformance 

5353 document for an implementation shall document the reasons for which a Locate Batch Job Request 

5354 may be rejected. 

5355 3.23.6 Modify Batch Job Request 

5356 Batch clients modify (alter) the attributes of a batch job by making a request to the server that 

5357 manages the batch job. Such a request is called a Modify Batch Job Request. 

5358 A batch server shall reject a Modify Batch Job Request if any of the following statements are true: 

5359 • The user of the batch client is not authorized to make the requested modification to the batch 

5360 job. 

5361 • The designated job is not managed by the batch server. 

5362 • The requested modification is inconsistent with the state of the batch job. 
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5363 • An unrecognized resource is requested for a batch job in an execution queue. 

5364 A batch server may reject a Modify Batch Job Request for other reasons. The conformance 

5365 document for an implementation shall describe the reasons for which a Modify Batch Job Request 

5366 may be rejected. The conformance document for an implementation shall describe the method 

5367 used to determine whether the user of a client is authorized to perform the requested action. 

5368 A batch server that accepts a Modify Batch Job Request shall modify all the specified attributes of 

5369 the batch job. A batch server that rejects a Modify Batch Job Request shall modify none of the 

5370 attributes of the batch job. 

5371 If the servicing by a batch server of an otherwise valid request would result in no change, then 

5372 the batch server shall indicate successful completion of the request. 

5373 3.23.7 Move Batch Job Request 

5374 A batch client can request that a batch server move a batch job to another destination. Such a 

5375 request is called a Move Batch Job Request. 

5376 A batch server shall reject a Move Batch Job Request if any of the following statements are true: 

5377 • The user of the batch client is not authorized to remove the designated job from the queue in 

5378 which the batch job resides. 

5379 • The user of the batch client is not authorized to move the designated job to the destination. 

5380 • The designated job is not managed by the batch server. 

5381 • The designated job is in the EXITING state. 

5382 • The destination is inaccessible. 

5383 A batch server can reject a Move Batch Job Request for other reasons. The conformance document 

5384 for an implementation shall describe the reasons for which a Move Batch Job Request may be 

5385 rejected. The conformance document for an implementation shall describe the method used to 

5386 determine whether the user of a client is authorized to perform the requested action. 

5387 A batch server that accepts a Move Batch Job Request shall perform the following services: 

5388 • Queue the designated job at the destination. 

5389 • Remove the designated job from the queue in which the batch job resides. 

5390 If the destination resides on another batch server, the batch server shall queue the batch job at 

5391 the destination by sending a Queue Batch Job Request to the other server. If the Queue Batch Job 

5392 Request fails, the batch server shall reject the Move Batch Job Request. If the Queue Batch Job Request 

5393 succeeds, the batch server shall remove the batch job from its queue. 

5394 The batch server shall not modify any attributes of the batch job. 

5395 3.23.8 Queue Batch Job Request 

5396 A batch queue is controlled by one and only one batch server. A batch server is said to own the 

5397 queues that it controls. Batch clients make requests of batch servers to have jobs queued. Such a 

5398 request is called a Queue Batch Job Request. 

5399 A batch server requested to queue a batch job for which the queue is unspecified shall select a 

5400 queue for the batch job. Such a queue is called the defaidt queue of the batch server. The 

5401 conformance document for the implementation shall document the means by which the batch 

5402 server determines the default queue. The implementation shall provide the means for a batch 

5403 administrator to specify the default queue. The queue, whether specified or defaulted, is called 
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5404 the target queue. 

5405 A batch server shall reject a Queue Batch Job Request if any of the following statements are true: 

5406 • The client is not authorized to create a batch job in the target queue. 

5407 • The request specifies a queue that does not exist on the batch server. 

5408 • The target queue is an execution queue and the batch server cannot satisfy a resource 

5409 requirement of the batch job. 

5410 • The target queue is an execution queue and an unrecognized resource is requested. 

5411 • The target queue is an execution queue, the batch server does not support checkpointing, and 

5412 the value of the Checkpoint attribute of the batch job is not NO_CHECKPOINT. 

5413 • The job requires access to a user identifier that the batch client is not authorized to access. 

5414 A batch server may reject a Queue Batch Job Request for other reasons. The conformance 

5415 document for an implementation shall document the reasons for which a Queue Batch Job Request 

5416 may be rejected. 

5417 A batch server that accepts a Queue Batch Job Request for a batch job for which the 

5418 PBS_0_QUEUE value is missing from the value of the Variable_List attribute of the batch job 

5419 shall add that variable to the list and set the value to the name of the target queue. Once set, no 

5420 server shall change the value of PBS_0_QUEUE, even if the batch job is moved to another 

5421 queue. 

5422 A batch server that accepts a Queue Batch Job Request for a batch job for which the PBS_JOBID 

5423 value is missing from the value of the Variable_List attribute shall add that variable to the list and 

5424 set the value to the batch job identifier assigned by the server in the format: 

5425 sequence_number. server 

5426 A batch server that accepts a Queue Batch Job Request for a batch job for which the 

5427 PBSJOBNAME value is missing from the value of the Variable_List attribute of the batch job 

5428 shall add that variable to the list and set the value to the Job_Name attribute of the batch job. 

5429 32.3.9 Batch Queue Status Request 

5430 A batch client can request that a batch server respond with the status and attributes of a queue. 

5431 Such a request is called a Batch Queue Status Request. 

5432 A batch server shall reject a Batch Queue Status Request if any of the following statements are true: 

5433 • The user of the batch client is not authorized to query the status of the designated queue. 

5434 • The designated queue does not exist on the batch server. 

5435 A batch server may reject a Batch Queue Status Request for other reasons. The conformance 

5436 document for an implementation shall describe the reasons for which a Batch Queue Status 

5437 Request is rejected. The conformance document for an implementation shall describe the method 

5438 used to determine whether the user of a client is authorized to perform the requested action. 

5439 A batch server that accepts a Batch Queue Status Request shall return a Batch Queue Status Reply to 

5440 the batch client. 
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5441 3.2.3.10 Release Batch Job Request 

5442 A batch client can request that server remove one or more holds from a batch job. Such a request 

5443 is called a Release Batch Job Request. 

5444 A batch server shall reject a Release Batch Job Request if any of the following statements are true: 

5445 • The user of the batch client is not authorized to remove one or more of the requested holds 

5446 from the batch job. 

5447 • The batch server does not manage the specified job. 

5448 A batch server may reject a Release Batch Job Request for other reasons. The conformance 

5449 document for an implementation shall document the reasons for which a Release Batch Job 

5450 Request may be rejected. The conformance document for an implementation shall describe the 

5451 method used to determine whether the user of a client is authorized to perform the requested 

5452 action. 

5453 A batch server that accepts a Release Batch Job Request shall remove each type of hold listed in the 

5454 Release Batch Job Request, that is present, from the value of the Hold_Types attribute of the batch 

5455 job. 

5456 3.2.3.11 Rerun Batch Job Request 

5457 To rerun a batch job is to kill the session leader of the batch job and leave the batch job eligible 

5458 for re-execution. A batch client can request that a batch server rerun a batch job. Such a request is 

5459 called Rerun Batch Job Request. 

5460 A batch server shall reject a Rerun Batch Job Request if any of the following statements are true: 

5461 • The user of the batch client is not authorized to rerun the designated job. 

5462 • The Rerunable attribute of the designated job has the value FALSE. 

5463 • The designated job is not in the RUNNING state. 

5464 • The batch server does not manage the designated job. 

5465 A batch server may reject a Rerun Batch Job Request for other reasons. The conformance document 

5466 for an implementation shall describe the reasons for which a Rerun Batch Job Request may be 

5467 rejected. The conformance document for an implementation shall describe the method used to 

5468 determine whether the user of a client is authorized to perform the requested action. 

5469 A batch server that rejects a Rerun Batch Job Request shall in no way modify the execution of the 

5470 batch job. 

5471 A batch server that accepts a request to rerun a batch job shall perform the following services: 

5472 • Requeue the batch job in the execution queue in which it was executing. 

5473 • Send a SIGKILL signal to the process group of the session leader of the batch job. 

5474 An implementation may indicate to the batch job owner that the batch job has been rerun. The 

5475 conformance document for an implementation shall state whether the batch job owner is 

5476 notified that a batch job is rerun, and if so, shall describe the means used. 

5477 A batch server that reruns a batch job may send other signals to the session leader of the batch 

5478 job prior to sending the SIGKILL signal. The conformance document for an implementation 

5479 shall describe any other signals that may be sent. 

5480 A batch server may preferentially select a rerun job for execution. The conformance document 

5481 for an implementation shall state whether rerun jobs shall be selected for execution before other 
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5482 jobs. 

5483 3.2.3.12 Select Batch Jobs Request 

5484 A batch client can request from a batch server a list of jobs managed by that server that match a 

5485 list of selection criteria. Such a request is called a Select Batch Jobs Request. All the batch jobs 

5486 managed by the batch server that receives the request are candidates for selection. 

5487 A batch server that accepts a Select Batch Jobs Request shall return a list of zero or more job 

5488 identifiers that correspond to jobs that meet the selection criteria. 

5489 If the batch client is not authorized to query the status of a batch job, the batch server shall not 

5490 select the batch job. 

5491 3.2.3.13 Server Shutdown Request 

5492 A batch server is defined to have shut down when it does not respond to requests from clients 

5493 and does not perform deferred services for jobs. A batch client can request that a batch server 

5494 shut down. Such a request is called a Server Shutdown Request. 

5495 A batch server shall reject a Server Shutdown Request from a client that is not authorized to shut 

5496 down the batch server. The conformance document for an implementation shall describe the 

5497 method used to determine whether the user of a client is authorized to perform the requested 

5498 action. 

5499 A batch server may reject a Server Shutdown Request for other reasons. The conformance 

5500 document for an implementation shall document the reasons for which a Server Shutdown 

5501 Request may be rejected. 

5502 At server shutdown, a batch server shall do, in order of preference, one of the following: 

5503 • If checkpointing is implemented and the batch job is checkpointable, then checkpoint the 

5504 batch job and requeue it. 

5505 • If the batch job is rerunable, then requeue the batch job to be rerun (restarted from the 

5506 beginning). 

5507 • Abort the batch job. 

5508 3.2.3.14 Server Status Request 

5509 A batch client can request that a batch server respond with the status and attributes of the batch 

5510 server. Such a request is called a Server Status Request. 

5511 A batch server shall reject a Server Status Request if the following statement is true: 

5512 • The user of the batch client is not authorized to query the status of the designated server. 

5513 A batch server may reject a Server Status Request for other reasons. The conformance document 

5514 for an implementation shall describe the reasons for which a Server Status Request may be 

5515 rejected. The conformance document for an implementation shall describe the method used to 

5516 determine whether the user of a client is authorized to perform the requested action. 

5517 A batch server that accepts a Server Status Request shall return a Server Status Reply to the batch 

5518 client. 
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5519 3.2.3.15 Signal Batch Job Request 

5520 A batch client can request that a batch server signal the session leader of a batch job. Such a 

5521 request is called a Signal Batch Job Request. 

5522 A batch server shall reject a Signal Batch Job Request if any of the following statements are true: 

5523 • The user of the batch client is not authorized to signal the batch job. 

5524 • The job is not in the RUNNING state. 

5525 • The batch server does not manage the designated job. 

5526 • The requested signal is not supported by the implementation. 

5527 A batch server may reject a Signal Batch Job Request for other reasons. The conformance 

5528 document for an implementation shall describe the reasons for which a Signal Batch Job Request 

5529 may be rejected. The conformance document for an implementation shall describe the method 

5530 used to determine whether the user of a client is authorized to perform the requested action. 

5531 A batch server that accepts a request to signal a batch job shall send the signal requested by the 

5532 batch client to the process group of the session leader of the batch job. 

5533 3.2.3.16 Track Batch Job Request 

5534 Track Batch Job Request is an optional feature of batch servers. If an implementation supports 

5535 Track Batch Job Request, the statements in this section apply and the configuration variable 

5536 POSIX2_PBS_TRACK shall be set to 1. 

5537 Track Batch Job Request provides a method for tracking the current location of a batch job. Clients 

5538 may use the tracking information to determine the batch server that should receive a batch 

5539 server request. 

5540 If Track Batch Job Request is supported by a batch server, then when the batch server queues a 

5541 batch job as a result of a Queue Batch Job Request, and the batch server is not the batch server that 

5542 created the batch job, the batch server shall send a Track Batch Job Request to the batch server that 

5543 created the job. 

5544 If Track Batch Job Request is supported by a batch server, then the Track Batch Job Request may also 

5545 be sent to other servers as a backup to the primary server. The method by which backup servers 

5546 are specified is implementation-dependent. 

5547 If Track Batch Job Request is supported by a batch server that receives a Track Batch Job Request, 

5548 then the batch server shall record the current location of the batch job as contained in the 

5549 request. 
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5550 3.3 Common Behavior for Batch Environment Utilities 


5551 3.3.1 Batch Job Identifier 

5552 A utility shall recognize job_identifiers of the format: 

5553 sequence_number [ . server_name] [@server] 

5554 where: 

5555 sequence_number An integer that, when combined with server_name, provides a batch job 

5556 identifier that is unique within the batch system. 

5557 server_name The name of the batch server to which the batch job was originally submitted. 

5558 server The name of the batch server that is currently managing the batch job. 

5559 If the application omits the batch server_name portion of a batch job identifier, a utility shall use 

5560 the name of a default batch server. 

5561 If the application omits the batch server portion of a batch job identifier, a utility shall use: 

5562 • The batch server indicated by server_name, if present. 

5563 • The name of the default batch server. 

5564 • The name of the batch server that is currently managing the batch job. 

5565 If only @server is specified, then the status of all jobs owned by the user on the requested server 

5566 is listed. 

5567 The means by which a utility determines the default batch server is implementation-dependent. 

5568 If the application presents the batch server portion of a batch job identifier to a utility, the utility 

5569 shall send the request to the specified server. 

5570 A strictly conforming application shall use the syntax described for the job identifier. Whenever 

5571 a batch job identifier is specified whose syntax is not recognized by an implementation, then a 

5572 message for each error that occurs shall be written to standard error and the utility shall exit 

5573 with an exit status greater than zero. 

5574 When a batch job identifier is supplied as an argument to a batch utility and the server_name 

5575 portion of the batch job identifier is omitted, then the utility shall use the name of the default 

5576 batch server. 


5577 When a batch job identifier is supplied as an argument to a batch utility and the batch server 

5578 portion of the batch job identifier is omitted, then the utility shall use either: 

5579 • The name of the default batch server 

5580 or: 

5581 • The name of the batch server that is currently managing the batch job 

5582 When a batch job identifier is supplied as an argument to a batch utility and the batch server 

5583 portion of the batch job identifier is specified, then the utility shall send the required Batch Server 

5584 Request to the specified server. 


156 


Technical Standard (2000) (Draft February 29, 2000) 




Batch Environment Services and Utilities Common Behavior for Batch Environment Utilities 


5585 3.3.2 Destination 


5586 The utility shall recognize a destination of the format: 

5587 [queue] [@server] 


5588 where: 


5589 queue 

5590 

5591 

5592 

5593 


The name of a valid execution or routing queue at the batch server denoted by 
@server, defined as a string of up to 15 alphanumeric characters in the portable 
character set (see the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set) where the first 
character is alphabetic. 


5594 server The name of a batch server, defined as a string of alphanumeric characters in 

5595 the portable character set. 


5596 


If the application omits the batch server portion of a destination, then the utility shall use either: 


5597 • The name of the default batch server 


5598 or: 

5599 • The name of the batch server that is currently managing the batch job 

5600 The means by which a utility determines the default batch server is implementation-dependent. 

5601 If the application omits the queue portion of a destination, then the utility shall use the name of 

5602 the default queue at the batch server chosen. 

5603 The means by which a batch server determines its default queue is implementation-dependent. 

5604 If a destination is specified in the queue@server form, then the utility shall use the specified queue 

5605 at the specified server. 

5606 A strictly conforming application shall use the syntax described for a destination. Whenever a 

5607 destination is specified whose syntax is not recognized by an implementation, then a message 

5608 shall be written to standard error and the utility shall exit with an exit status greater than zero. 


5609 3.3.3 Multiple Keyword-Value Pairs 


5610 For each option that can have multiple keyword-value pair arguments, the following rules shall 

5611 apply. Examples of options that can have list-oriented option-arguments are -u valne@keyword 

5612 and -1 keyivord-value. 


5613 

5614 

5615 

5616 

5617 


1. If a batch utility is presented with a list-oriented option-argument for which a keyword has 
a corresponding value that begins with a single or double quote, then the utility shall stop 
interpreting the input stream for delimiters until a second single or double quote, 
respectively, is encountered. This feature allows some flexibility for a comma (' , ') or 
equals sign (' = ') to be part of the value string for a particular keyword; for example: 


5618 


keywdl='vail,val2',keywd2="val3,val4" 


5619 


Note: This may require the user to escape the quotes as in the following command: 


5620 


foo —xkeywdl = \'vail, val2 \' , keywd2 = \"val3, val4\" 


5621 

5622 

5623 


2. If a batch server is presented with a list-oriented attribute that has a keyword that was 
encountered earlier in the list, then the later entry for that keyword shall replace the earlier 
entry. 


5624 3. If a batch server is presented with a list-oriented attribute that has a keyword without any 

5625 corresponding value of the form keyword = or @keyivord and the same keyword was 
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5626 

5627 


encountered earlier in the list, then the prior entry for that keyword shall be ignored by the 
batch server. 


5628 

5629 

5630 

5631 

5632 


4. If a batch utility is expecting a list-oriented option-argument entry of the form 
keyword-value, but is presented with an entry of the form keyword without any 
corresponding value, then the entry shall be treated as though a default value of NULL was 
assigned (that is, keyword = NULL) for entry parsing purposes. The utility shall include only 
the keyword, not the NULL value, in the associated job attribute. 


5633 

5634 

5635 

5636 

5637 


5. If a batch utility is expecting a list-oriented option-argument entry of the form 
valne@keyword , but is presented with an entry of the form value without any corresponding 
keyword, then the entry shall be treated as though a keyword of NULL was assigned (that 
is, zw/ne@NULL) for entry parsing purposes. The utility shall include only the value, not 
the NULL keyword, in the associated job attribute. 


5638 

5639 

5640 

5641 


6. A batch server shall accept a list-oriented attribute that has multiple occurrences of the 
same keyword, interpreting the keywords, in order, with the last value encountered taking 
precedent over prior instances of the same keyword. This rule allows, but does not require, 
a batch utility to preprocess the attribute to remove duplicate keywords. 


5642 

5643 

5644 

5645 

5646 

5647 

5648 

5649 


7. If a batch utility is presented with multiple list-oriented option-arguments on the 
command line or in script directives, or both, for a single option, then the utility shall 
concatenate, in order, any command line keyword and value pairs to the end of any 
directive keyword and value pairs separated by a single comma to produce a single string 
that is an equivalent, valid option-argument. The resulting string shall be assigned to the 
associated attribute of the batch job (after optionally removing duplicate entries as 
described in item 6. 
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Chapter 4 

Utilities 


5651 This chapter contains the definitions of the utilities, as follows: 

5652 • Mandatory utilities that are present on every conformant system 

5653 • Optional utilities that are present only on systems supporting the associated option; see 

5654 Section 1.8.1 on page 14 for information on the options in this volume of 

5655 IEEE Std. 1003.1-200x 
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5656 NAME 

5657 admin — create and administer SCCS files (DEVELOPMENT) 

5658 SYNOPSIS 

5659 XSI 

5660 

5661 

5662 

5663 admin [—a login] [—d flag ] [—m mrlist] [—r rel] [—t [name] ] file . . . 

5664 admin —h file ... 

5665 admin —z file ... 

5666 


admin —i [name ][—n][—a login ][—d flag ][—f flag ][—m mrlist ][—r rel] 

[—t [name] [—y [comment]] newfile 

admin —n[—a login ][—d flag ][—f flag ][—m mrlist] [—t [name]][—y[comment]] 
newfile ... 


5667 DESCRIPTION 

5668 The admin utility shall create new SCCS files or change parameters of existing ones. If a named 

5669 file does not exist, it shall be created, and its parameters shall be initialized according to the 

5670 specified options. Parameters not initialized by an option shall be assigned a default value. If a 

5671 named file does exist, parameters corresponding to specified options shall be changed, and other 

5672 parameters shall be left as is. 

5673 All SCCS file names supplied by the application shall be of the form s .filename. New SCCS files I 

5674 shall be given read-only permission mode. Write permission in the parent directory is required I 

5675 to create a file. All writing done by admin shall be to a temporary x-file, named x.filename (see get) I 

5676 created with read-only mode if admin is creating a new SCCS file, or created with the same mode 

5677 as that of the SCCS file if the file already exists. After successful execution of admin, the SCCS file 

5678 shall be removed (if it exists), and the x-file shall be renamed with the name of the SCCS file. This 

5679 ensures that changes are made to the SCCS file only if no errors occur. 

5680 The admin utility shall also use a transient lock file (named z filename), which is used to prevent 

5681 simultaneous updates to the SCCS file; see get on page 510. 


5682 OPTIONS 

5683 The admin utility shall conform to the System Interface Definitions volume of I 

5684 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that the -i, -t, and -y I 

5685 options have optional option-arguments. These optional option-arguments cannot be presented 

5686 as separate arguments. The following options are supported: 


5687 -n 

5688 


Create a new SCCS file. When -n is used without -i, the SCCS file is created with 
control information but without any file data. 


5689 

5690 

5691 

5692 

5693 

5694 


-i [name] Specify the name of a file from which the text for a new SCCS file is to be taken. The 
text constitutes the first delta of the file (see the -r option for delta numbering 
scheme). If the -i option is used, but the name option-argument is omitted, the text 
is obtained by reading the standard input. If this option is omitted, the SCCS file is 
created with control information but without any file data. The -i option implies 
the -n option. 


5695 

5696 

5697 


-r rel Specify the release into which the initial delta is inserted. If the -r option is not 

used, the initial delta is inserted into release 1. The level of the initial delta is 
always 1 (by default, initial deltas are named 1.1). 


5698 

5699 


-t [name] 


Specify the name of a file from which descriptive text for the SCCS file is to be 
taken. In the case of existing SCCS files (neither -i nor -n is specified): 
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5700 

5701 


• A -t option without a name option-argument causes the removal of descriptive 
text (if any) currently in the SCCS file. 

5702 

5703 


• A -t option with a name option-argument causes the text (if any) in the named 
file to replace the descriptive text (if any) currently in the SCCS file. 

5704 

5705 

5706 


Specify a flag, and, possibly, a value for the flag, to be placed in the SCCS file. 
Several -f options may be supplied on a single admin command line. The allowable 
flags and their values are: 

5707 


b 

Allow use of the -b option on a get command to create branch deltas. 

5708 

5709 

5710 


c ceil 

Specify the highest release (that is, ceiling), a number less than or equal to 
9 999, which may be retrieved by a get command for editing. The default 
value for an unspecified c flag is 9 999. 

5711 

5712 

5713 


f 'floor 

Specify the lowest release (that is, floor), a number greater than 0 but less 
than 9 999, which may be retrieved by a get command for editing. The 
default value for an unspecified f flag is 1. 

5714 


d SID 

Specify the default delta number (SID) to be used by a get command. 

5715 

5716 

5717 

5718 

5719 

5720 

5721 


i str 

Treat the "No ID keywords" message issued by get or delta as a fatal 
error. In the absence of this flag, the message is only a warning. The 
message is issued if no SCCS identification keywords (see get on page 
510) are found in the text retrieved or stored in the SCCS file. If a value is 
supplied, the application shall ensure that the keywords exactly match 
the given string; however, the string shall contain a keyword, and no 
embedded <newline>s. 

5722 

5723 

5724 


j 

Allow concurrent get commands for editing on the same SID of an SCCS 
file. This allows multiple concurrent updates to the same version of the 
SCCS file. 

5725 

5726 

5727 


Hist 

Specify a list of releases to which deltas can no longer be made (that is, get 
-e against one of these locked releases fails). The list has the following 
syntax: 

5728 

5729 



<list> ::= <range> I <list>, <range> 

<range> ::= SID | a 

5730 

5731 



The character a in the list is equivalent to specifying all releases for the 
named SCCS file. 

5732 

5733 

5734 

5735 

5736 

5737 

5738 


n 

Cause delta to create a null delta in each of those releases (if any) being 
skipped when a delta is made in a new release (for example, in making 
delta 5.1 after delta 2.7, releases 3 and 4 are skipped). These null deltas 
serve as anchor points so that branch deltas may later be created from 
them. The absence of this flag causes skipped releases to be nonexistent 
in the SCCS file, preventing branch deltas from being created from them 
in the future. 

5739 

5740 


q text 

Substitute user-definable text for all occurrences of the %Q% keyword in 
the SCCS file text retrieved by get. 

5741 

5742 

5743 

5744 


m mod 

Specify the module name of the SCCS file substituted for all occurrences 
of the %M% keyword in the SCCS file text retrieved by get. If the m flag 
is not specified, the value assigned is the name of the SCCS file with the 
leading ' .' removed. 
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5745 

5746 


t type Specify the type of module in the SCCS file substituted for all occurrences 

of the %Y% keyword in the SCCS file text retrieved by get. 


5747 

5748 

5749 

5750 

5751 


vpgm Cause delta to prompt for modification request (MR) numbers as the 
reason for creating a delta. The optional value specifies the name of an 
MR number validation program. (If this flag is set when creating an SCCS I 
file, the application shall ensure that the m option is also used even if its I 
value is null.) I 


5752 

5753 

5754 

5755 


-d flag Remove (delete) the specified flag from an SCCS file. Several -d options may be 

supplied on a single admin command. See the -f option for allowable flag names. 
(The 1 list flag gives a list of releases to be unlocked. See the -f option for further 
description of the 1 flag and the syntax of a list.) 


5756 

5757 

5758 

5759 

5760 

5761 

5762 


-a login Specify a login name, or numerical group ID, to be added to the list of users who 
may make deltas (changes) to the SCCS file. A group ID is equivalent to specifying 
all login names common to that group ID. Several -a options may be used on a 
single admin command line. As many logins, or numerical group IDs, as desired 
may be on the list simultaneously. If the list of users is empty, then anyone may 
add deltas. If login or group ID is preceded by a ' !', the users so specified are 
denied permission to make deltas. 


5763 

5764 

5765 

5766 


-e login Specify a login name, or numerical group ID, to be erased from the list of users 
allowed to make deltas (changes) to the SCCS file. Specifying a group ID is 
equivalent to specifying all login names common to that group ID. Several -e 
options may be used on a single admin command line. 


5767 

5768 

5769 


-y [comment] Insert the comment text into the SCCS file as a comment for the initial delta in a 
manner identical to that of delta. In the POSIX locale, omission of the -y option 
results in a default comment line being inserted in the form: 


5770 


"date and time created %s %s by 


<date>, <time>, <login> 


5771 

5772 


where <date> is expressed in the date utility's %y/%m/%d format, <time> in the 
date utility's %T format, and <login> is the login name of the user creating the file. 


5773 

5774 

5775 

5776 

5777 


-m mrlist Insert the list of modification request (MR) numbers into the SCCS file as the 

reason for creating the initial delta in a manner identical to delta. The application I 
shall ensure that the v flag is set and the MR numbers are validated if the v flag has I 
a value (the name of an MR number validation program). Diagnostics occur if the 
v flag is not set or MR validation fails. 


5778 -h 

5779 

5780 

5781 


Check the structure of the SCCS file and compare the newly computed checksum 
(the sum of all the characters in the SCCS file except those in the first line) with the 
checksum that is stored in the first line of the SCCS file. Appropriate error 
diagnostics are produced. 


5782 -z 

5783 

5784 


Recompute the SCCS file checksum and store it in the first line of the SCCS file (see 
the -h option above). Note that use of this option on a truly corrupted file may 
prevent future detection of the corruption. 


5785 OPERANDS 

5786 The following operands shall be supported: 


5787 

5788 

5789 

5790 


file A path name of an existing SCCS file or a directory. If file is a directory, admin 

behaves as though each file in the directory were specified as a named file, except 
that non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. 
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5791 newfile A path name of an SCCS file to be created. 

5792 If a single instance of file or newfile is specified as ' , the standard input is read; each line of the 

5793 standard input is taken to be the name of an SCCS file to be processed. Non-SCCS files and 

5794 unreadable files are silently ignored. 

5795 STDIN 

5796 The standard input shall be a text file used only if the -i is specified without an option-argument 

5797 or if a file or newfile operand is specified as ' . If the first character of any standard input line is 

5798 SOH (binary 001), the results are unspecified. 

5799 INPUT FILES 

5800 The existing SCCS files are text files of an unspecified format. The file named by the -i option's 

5801 name option-argument is a text file; if the first character of any line in this file is SOH (binary 

5802 001), the results are unspecified. 


5803 ENVIRONMENT VARIABLES 

5804 The following environment variables shall affect the execution of admin: 


5805 

5806 

5807 

5808 

5809 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


5810 LC_ALL If set to a non-empty string value, override the values of all the other 

5811 internationalization variables. 


5812 

5813 

5814 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


5815 

5816 

5817 

5818 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and the contents of the default -y 
comment. 


5819 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


5820 ASYNCHRONOUS EVENTS 

5821 Default. 


5822 STDOUT 

5823 Not used. 


5824 STDERR 

5825 Used only for diagnostic messages. 

5826 OUTPUT FILES 

5827 Any SCCS files created shall be text files of an unspecified format. During processing of a file, a 

5828 locking z-file, as described in get on page 510, may be created and deleted. 

5829 EXTENDED DESCRIPTION 

5830 None. 


5831 EXIT STATUS 

5832 The following exit values shall be returned: 

5833 0 Successful completion. 
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5834 >0 An error occurred. 

5835 CONSEQUENCES OF ERRORS 

5836 Default. 

5837 APPLICATION USAGE 

5838 It is recommended that directories containing SCCS files be writable by the owner only, and that 

5839 SCCS files themselves be read-only. The mode of the directories should allow only the owner to 

5840 modify SCCS files contained in the directories. The mode of the SCCS files prevents any 

5841 modification at all except by SCCS commands. 

5842 EXAMPLES 

5843 None. 

5844 RATIONALE 

5845 None. 

5846 FUTURE DIRECTIONS 

5847 A version of admin that fully supports the System Interface Definitions volume of I 

5848 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines may be introduced in a future I 

5849 issue. I 

5850 SEE ALSO 

5851 delta, get, prs, what 

5852 CHANGE HISTORY 

5853 First released in Issue 2. 

5854 Issue 4 

5855 Format reorganized. 

5856 Conformance to Utility Syntax Guidelines mandated, with exceptions as noted. 

5857 Internationalized environment variable support mandated. I 

5858 Issue 6 I 

5859 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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5860 NAME 

5861 alias — define or display aliases 

5862 SYNOPSIS 

5863 UP alias [ alias-name[=string ] ...] 

5864 

5865 DESCRIPTION 

5866 The alias utility shall create or redefine alias definitions or write the values of existing alias 

5867 definitions to standard output. An alias definition provides a string value that shall replace a 

5868 command name when it is encountered; see Section 2.3.1 on page 40. 

5869 An alias definition shall affect the current shell execution environment and the execution 

5870 environments of the subshells of the current shell. When used as specified by this volume of 

5871 IEEE Std. 1003.1-200x, the alias definition shall not affect the parent process of the current shell 

5872 nor any utility environment invoked by the shell; see Section 2.12 on page 90. 

5873 OPTIONS 

5874 None. 

5875 OPERANDS 

5876 The following operands shall be supported: 

5877 alias-name Write the alias definition to standard output. 

5878 alias-name=string 

5879 Assign the value of string to the alias alias-name. 

5880 If no operands are given, all alias definitions shall be written to standard output. 

5881 STDIN 

5882 Not used. 

5883 INPUT FILES 

5884 None. 


5885 ENVIRONMENT VARIABLES 

5886 The following environment variables shall affect the execution of alias: 


5887 

5888 

5889 

5890 

5891 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


5892 

5893 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


5894 

5895 

5896 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


5897 LC_MESSAGES 

5898 Determine the locale that should be used to affect the format and contents of 

5899 diagnostic messages written to standard error. 

5900 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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5901 ASYNCHRONOUS EVENTS 

5902 Default. 

5903 STDOUT 

5904 The format for displaying aliases (when no operands or only name operands are specified) shall 

5905 be: 

5906 "%s=%s\n", name, value 

5907 The value string shall be written with appropriate quoting so that it is suitable for reinput to the 

5908 shell. See the description of shell quoting in Section 2.2 on page 36. 

5909 STDERR 

5910 Used only for diagnostic messages. 

5911 OUTPUT FILES 

5912 None. 

5913 EXTENDED DESCRIPTION 

5914 None. 

5915 EXIT STATUS 

5916 The following exit values shall be returned: 

5917 0 Successful completion. 

5918 >0 One of the name operands specified did not have an alias definition, or an error occurred. 

5919 CONSEQUENCES OF ERRORS 

5920 Default. 

5921 APPLICATION USAGE 

5922 Application writers should note that this utility need not be provided on systems that do not 

5923 support the User Portability Utilities option. 

5924 EXAMPLES 

5925 1. Change Is to give a columnated, more annotated output: 

5926 alias ls="ls —CF" 

5927 2. Create a simple "redo" command to repeat previous entries in the command history file: 

5928 alias r=' fc —s' 

5929 3. Use IK units for dn: 

5930 alias du=du\ — k 

5931 4. Set up nolinp so that it can deal with an argument that is itself an alias name: 

5932 alias nohup="nohup " 

5933 RATIONALE 

5934 The alias description is based on historical KomShell implementations. Known differences exist 

5935 between that and the C shell. The KomShell version was adopted to be consistent with all the 

5936 other KomShell features in this volume of IEEE Std. 1003.1-200x, such as command line editing. 

5937 Since alias affects the current shell execution environment, it is generally provided as a shell 

5938 regular built-in. 

5939 Historical versions of the KomShell have allowed aliases to be exported to scripts that are 

5940 invoked by the same shell. This is triggered by the alias -x flag; it is allowed by this volume of 

5941 IEEE Std. 1003.1-200x only when an explicit extension such as -x is used. The standard 
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5942 developers considered that aliases were of use primarily to interactive users and that they 

5943 should normally not affect shell scripts called by those users; functions are available to such 

5944 scripts. 

5945 Historical versions of the KomShell had not written aliases in a quoted manner suitable for 

5946 reentry to the shell, but this volume of IEEE Std. 1003.1-200x has made this a requirement for all 

5947 similar output. Therefore, consistency with this volume of IEEE Std. 1003.1-200x was chosen 

5948 over this detail of historical practice. 

5949 FUTURE DIRECTIONS 

5950 None. 

5951 SEE ALSO 

5952 Section 2.9.5 on page 79 

5953 CHANGE HISTORY 

5954 First released in Issue 4. 

5955 Issue 6 

5956 This utility is now marked as part of the User Portability Utilities option. 

5957 The APPLICATION USAGE section is added. 
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5958 NAME 

5959 ar — create and maintain library archives 

5960 SYNOPSIS 

5961 SD ar —d[—v] archive file . . . 

5962 

5963 xsi ar —m[—abiv] [ posname ] archive file . . . 

5964 

5965 xsi ar —p[—v] [-s] archive [file ...] 

5966 xsi ar — q[— cv] archive file . . . 

5967 

5968 xsi ar — r [—cuv] [—abi] [ posname ] archive file . . . 

5969 xsi ar —t [—v] [-s] archive [file ...] 

5970 xsi ar —x[—v] [— sCT] archive [file ...] 

5971 DESCRIPTION 

5972 The ar utility can be used to create and maintain groups of files combined into an archive. Once 

5973 an archive has been created, new files can be added, and existing files can be extracted, deleted, 

5974 or replaced. When an archive consists entirely of valid object files, the implementation shall 

5975 format the archive so that it is usable as a library for link editing (see c89, cc, and fori 77). When 

5976 some of the archived files are not valid object files, the suitability of the archive for library use is 

5977 xsi undefined. If an archive file consists entirely of printable files, the entire archive file is printable. 

5978 When ar creates an archive file, it creates administrative information indicating whether a 

5979 symbol table is present in the archive. When there is at least one object file that ar recognizes as 

5980 such in the archive, an archive symbol table is created in the archive file and maintained by ar ; it 

5981 is used by the link editor to search the archive file. Whenever the ar utility is used to create or 

5982 update the contents of such an archive, the symbol table is rebuilt. The -s option forces the 

5983 symbol table to be rebuilt. 

5984 All file operands can be path names. However, files within archives shall be named by a file 

5985 name, which is the last component of the path name used when the file was entered into the 

5986 archive. The comparison of file operands to the names of files in archives shall be performed by 

5987 comparing the last component of the operand to the name of the archive file. 

5988 It is unspecified whether multiple files in the archive may be identically named. In the case of 

5989 xsi such files, however, each file and posname operand shall match only the first archive file having a 

5990 name that is the same as the last component of the operand. 

5991 OPTIONS 

5992 The ar utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

5993 Section 12.2, Utility Syntax Guidelines. I 

5994 The following options shall be supported: 

5995 xsi -a Position new files in the archive after the file named by the posname operand. 

5996 xsi -b Position new files in the archive before the file named by the posname operand. 

5997 -c Suppress the diagnostic message that is written to standard error by default when 

5998 the archive file archive is created. 

-C Prevent extracted files from replacing like-named files in the file system. This 

option is useful when -T is also used, to prevent truncated file names from 
replacing files with the same prefix. 


5999 XSI 

6000 
6001 
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6002 

-d 

Delete one or movefiles from archive. 

6003 XSI 

-i 

Position new files in the archive before the file named by the posname operand 

6004 


(equivalent to -b). 

6005 XSI 

-m 

Move the named files. The -a, -b, or -i options with the posname operand indicate 

6006 


the position; otherwise, move the files to the end of the archive. 

6007 

-P 

Write the contents of the files from archive to the standard output. If no files are 

6008 


specified, the contents of all files in the archive shall be written in the order of the 

6009 


archive. 


6010 XSI 

6011 
6012 

6013 -r Replace or add files to archive. If the archive named by archive does not exist, a 

6014 new archive file shall be created and a diagnostic message shall be written to 

6015 standard error (unless the -c option is specified). If no files are specified and the 

6016 archive exists, the results are undefined. Files that replace existing files shall not 

6017 change the order of the archive. Files that do not replace existing files shall be 

6018 xsi appended to the archive unless a -a, -b, or -i option specifies another position. 


-q Quickly append the named files to the end of the archive file. In this case ar does 

not check whether the added members are already in the archive. This is useful to 
bypass the searching otherwise done when creating a large archive piece by piece. 


6019 xsi -s Force the regeneration of the archive symbol table even if ar is not invoked with an 

6020 option that modifies the archive file contents. This option is useful to restore the 

6021 archive symbol table after it has been stripped; see strip. 


6022 -t Write a table of contents of archive to the standard output. The files specified by the 

6023 file operands shall be included in the written list. If no file operands are specified, 

6024 all files in archive shall be included in the order of the archive. 


6025 xsi -T Allow file name truncation of extracted files whose archive names are longer than 

6026 the file system can support. By default, extracting a file with a name that is too 

6027 l° n g is an error; a diagnostic message is written and the file is not extracted. 


6028 -U 

6029 

6030 


Update older files. When used with the -r option, files within the archive are 
replaced only if the corresponding file has a modification time that is at least as 
new as the modification time of the file within the archive. 


6031 -v 

6032 

6033 


Give verbose output. When used with the option characters -d, -r, or -x, write a 
detailed file-by-file description of the archive creation and maintenance activity, as 
described in the STDOUT section. 


6034 

6035 


When used with -p, write the name of the file to the standard output before 
writing the file itself to the standard output, as described in the STDOUT section. 


6036 

6037 


When used with -t, include a long listing of information about the files within the 
archive, as described in the STDOUT section. 


6038 -X 

6039 

6040 

6041 


Extract the files named by the file operands from archive. The contents of the 
archive file shall not be changed. If no file operands are given, all files in the 
archive shall be extracted. The modification time of each file extracted shall be set 
to the time the file is extracted from the archive. 


6042 OPERANDS 

6043 The following operands shall be supported: 

6044 archive A path name of the archive file. 
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6045 

6046 

6047 

6048 

6049 


file A path name. Only the last component shall be used when comparing against the 

names of files in the archive. If two or more file operands have the same last path 
name component (basename), the results are unspecified. The implementation's 
archive format shall not truncate valid file names of files added to or replaced in 
the archive. 


6050 xsi posname The name of a file in the archive file, used for relative positioning; see options -m 

6051 and -r. 

6052 STDIN 

6053 Not used. 


6054 INPUT FILES 

6055 The input file named by archive shall be a file in the format created by ar -r. 


6056 ENVIRONMENT VARIABLES 

6057 The following environment variables shall affect the execution of ar: 


6058 

6059 

6060 
6061 
6062 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


6063 

6064 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


6065 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

6066 characters (for example, single-byte as opposed to multi-byte characters in 

6067 arguments and input files). 

6068 LC_MESSAGES 

6069 Determine the locale that should be used to affect the format and contents of 

6070 diagnostic messages written to standard error. 

6071 LC_TIME Determine the format and content for date and time strings written by ar -tv. 

6072 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

6073 TMPDIR Determine the path name that overrides the default directory for temporary files, if 

6074 any. 


6075 ASYNCHRONOUS EVENTS 

6076 Default. 


6077 

6078 

6079 

6080 
6081 
6082 

6083 

6084 

6085 


STDOUT 

If the -d option is used with the -v option, the standard output format shall be: 

"d — %s\n", <file> 

where file is the operand specified on the command line. 

If the -p option is used with the -v option, ar shall precede the contents of each file with: 

"\n<%s>\n\n", <file> 

where file is the operand specified on the command line, iifile operands were specified, and the 
name of the file in the archive if they were not. 

If the -r option is used with the -v option: 
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6086 

6087 

6088 

6089 

6090 

6091 

6092 

6093 


• lifile is already in the archive, the standard output format shall be: 

"r — %s\n", <file> 

where <file> is the operand specified on the command line. 

• It file is not already in the archive, the standard output format shall be: 

"a — %s\n", <file> 

where <file> is the operand specified on the command line. 

If the -t option is used, ar shall write the names of the files to the standard output in the format: 

"%s\n", <file> 


6094 where file is the operand specified on the command line, it file operands were specified, or the 

6095 name of the file in the archive if they were not. 

6096 If the -t option is used with the -v option, the standard output format shall be: 

6097 "%s %u/%u %u %s %d %d:%d %d %s\n", <member mode >, <user ID>, 

6098 <group ID> , <number of bytes in member> , 

6099 <abbreviated month>, <day-of-month> , <hour>, 

6100 <minute> r <year>, <file> 

6101 where: 


6102 <file> Shall be the operand specified on the command line, if file operands were specified, 

6103 or the name of the file in the archive if they were not. 


6104 

6105 

6106 

6107 

6108 


<member 

Shall be formatted the same as the <file mode> string defined in the STDOUT section of 
Is, except that the first character, the <entry type>, is not used; the string represents 
the file mode of the archive member at the time it was added to or replaced in the 
archive. 


6109 

6110 

6111 

6112 

6113 

6114 

6115 

6116 

6117 

6118 

6119 

6120 
6121 


The following represent the last-modification time of a file when it was most recently added to 
or replaced in the archive: 

<abbreviated month> 

Equivalent to the %b format in date. 

<day-of-month> 

Equivalent to the %e format in date. 

<hour> Equivalent to the %H format in date. 

<minute> Equivalent to the %M format in date. 

<year> Equivalent to the %Y format in date. 

When LC_TIME does not specify the POSIX locale, a different format and order of presentation 
of these fields relative to each other may be used in a format appropriate in the specified locale. 

If the -x option is used with the -v option, the standard output format shall be: 

"x — %s\n", <file> 


6122 where file is the operand specified on the command line, it file operands were specified, or the 

6123 name of the file in the archive if they were not. 


Commands and Utilities, Issue 6 


171 



ar 


Utilities 


6124 STDERR 

6125 Used only for diagnostic messages. The diagnostic message about creating a new archive when 

6126 -c is not specified shall not modify the exit status. 

6127 OUTPUT FILES 

6128 Archives are files with unspecified formats. 

6129 EXTENDED DESCRIPTION 

6130 None. 

6131 EXIT STATUS 

6132 The following exit values shall be returned: 

6133 0 Successful completion. 

6134 >0 An error occurred. 

6135 CONSEQUENCES OF ERRORS 

6136 Default. 

6137 APPLICATION USAGE 

6138 None. 

6139 EXAMPLES 

6140 None. 

6141 RATIONALE 

6142 The archive format is not described. It is recognized that there are several known ar formats, 

6143 which are not compatible. The ar utility is included, however, to allow creation of archives that 

6144 are intended for use only on one machine. The archive file is specified as a file, and it can be 

6145 moved as a file. This does allow an archive to be moved from one machine to another machine 

6146 that uses the same implementation of ar. 

6147 Utilities such as pax (and its forebears tar and cpio) also provide portable "archives". This is a not 

6148 a duplication; the ar utility is included to provide an interface primarily for make and the 

6149 compilers, based on a historical model. 

6150 In historical implementations, the -q option (available on XSI-conforming systems) is known to 

6151 execute quickly because ar does not check on whether the added members are already in the 

6152 archive. This is useful to bypass the searching otherwise done when creating a large archive 

6153 piece-by-piece. These remarks may but need not remain true for a brand new implementation of 

6154 this utility; hence, these remarks have been moved into the RATIONALE. 

6155 BSD implementations historically required applications to provide the -s option whenever the 

6156 archive was supposed to contain a symbol table. As in this volume of IEEE Std. 1003.1-200x, 

6157 System V historically creates or updates an archive symbol table whenever an object file is 

6158 removed from, added to, or updated in the archive. 

6159 The OPERANDS section requires what might seem to be true without specifying it: the archive 

6160 cannot truncate the file names below |NAME_MAX}. Some historical implementations do so, 

6161 however, causing unexpected results for the application. Therefore, this volume of 

6162 IEEE Std. 1003.1-200x makes the requirement explicit to avoid misunderstandings. 

6163 According to the System V documentation, the options -dmpqrtx are not required to begin with 

6164 a hyphen ('-'). This volume of IEEE Std. 1003.1-200x requires that a conforming application 

6165 use the leading hyphen. 

6166 The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as 

6167 an example: 
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6168 A file created by ar begins with the "magic" string "! <arch>\n". The rest of the archive is 

6169 made up of objects, each of which is composed of a header for a file, a possible file name, and 

6170 the file contents. The header is portable between machine architectures, and, if the file 

6171 contents are printable, the archive is itself printable. 

6172 The header is made up of six ASCII fields, followed by a two-character trailer. The fields are 

6173 the object name (16 characters), the file last modification time (12 characters), the user and 

6174 group IDs (each 6 characters), the file mode (8 characters), and the file size (10 characters). All 

6175 numeric fields are in decimal, except for the file mode, which is in octal. 

6176 The modification time is the file stjntime field. The user and group IDs are the file st_uid and 

6177 st_gid fields. The file mode is the file st_mode field. The file size is the file st_size field. The 

6178 two-byte trailer is the string "<newline>". 

6179 Only the name field has any provision for overflow. If any file name is more than 16 

6180 characters in length or contains an embedded space, the string " # 1 / " followed by the ASCII 

6181 length of the name is written in the name field. The file size (stored in the archive header) is 

6182 incremented by the length of the name. The name is then written immediately following the 

6183 archive header. 

6184 Any unused characters in any of these fields are written as <space> characters. If any fields 

6185 are their particular maximum number of characters in length, there is no separation between 

6186 the fields. 

6187 Objects in the archive are always an even number of bytes long; files that are an odd number 

6188 of bytes long are padded with a <newline> character, although the size in the header does 

6189 not reflect this. 

6190 The ar utility description requires that (when all its members are valid object files) ar produce an 

6191 object code library, which the linkage editor can use to extract object modules. If the linkage 

6192 editor needs a symbol table to permit random access to the archive, ar must provide it; however, 

6193 ar does not require a symbol table. 

6194 The BSD -o option was omitted. It is a rare portable application that uses ar to extract object 

6195 code from a library with concern for its modification time, since this can only be of importance 

6196 to make. Hence, since this functionality is not deemed important for applications portability, the 

6197 modification time of the extracted files is set to the current time. 

6198 There is at least one known implementation (for a small computer) that can accommodate only 

6199 object files for that system, disallowing mixed object and other files. The ability to handle any 

6200 type of file is not only historical practice for most implementations, but is also a reasonable 

6201 expectation. 

6202 Consideration was given to changing the output format of ar -tv to the same format as the 

6203 output of Is -1. This would have made parsing the output of ar the same as that of Is. This was 

6204 rejected in part because the current ar format is commonly used and changes would break 

6205 historical usage. Second, ar gives the user ID and group ID in numeric format separated by a 

6206 slash. Changing this to be the user name and group name would not be correct if the archive 

6207 were moved to a machine that contained a different user database. Since ar cannot know 

6208 whether the archive file was generated on the same machine, it cannot tell what to report. 

6209 The text on the -ur option combination is historical practice—since one file name can easily 

6210 represent two different files (for example, /a/foo and /b/foo), it is reasonable to replace the 

6211 member in the archive even when the modification time in the archive is identical to that in the 

6212 file system. 
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6213 FUTURE DIRECTIONS 

6214 None. I 

6215 SEE ALSO 

6216 c89, pax, strip the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, I 

6217 Headers, <unistd.h> description of {POSIX_NO_TRUNC} I 

6218 CHANGE HISTORY 

6219 First released in Issue 2. 

6220 Issue 4 

6221 Aligned with the ISO/IEC 9945-2:1993 standard. 

6222 The -C and -T options are added. 

6223 Issue 5 

6224 FUTURE DIRECTIONS section added. 

6225 Issue 6 

6226 This utility is now marked as part of the Software Development Utilities option. I 

6227 The STDOUT description is changed for the -v option to align with the IEEE P1003.2b draft I 

6228 standard. I 

6229 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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6230 NAME 

6231 asa — interpret carriage-control characters 

6232 SYNOPSIS 

6233 FR asa [file...] 

6234 


6235 DESCRIPTION 

6236 The asa utility shall write its input files to standard output, mapping carriage-control characters 

6237 from the text files to line-printer control sequences in an implementation-dependent manner. 

6238 The first character of every line shall be removed from the input, and the following actions are 

6239 performed: 

6240 If the character removed is: 


6241 <space> The rest of the line is output without change. 


6242 

6243 

6244 


0 A <newline> character is output, then the rest of the input line. 

1 One or more implementation-dependent characters that causes an advance to the next 

page shall be output, followed by the rest of the input line. 


6245 

6246 

6247 

6248 


+ The <newline> character of the previous line shall be replaced with one or more 

implementation-dependent characters that causes printing to return to column position 
1, followed by the rest of the input line. If the ' + ' is the first character in the input, it 
shall have the same effect as the <space> character. 


6249 The action of the asa utility is unspecified upon encountering any character other than those 

6250 listed above as the first character in a line. 


6251 OPTIONS 

6252 None. 


6253 OPERANDS 


6254 file A path name of a text file used for input. If no file operands are specified, the 

6255 standard input shall be used. 

6256 STDIN 

6257 The standard input is used only if no file operands are specified; see the INPUT FILES section. 

6258 INPUT FILES 

6259 The input files shall be text files. 


6260 ENVIRONMENT VARIABLES 

6261 The following environment variables shall affect the execution of asa: 


6262 

6263 

6264 

6265 

6266 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


6267 

6268 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


6269 

6270 

6271 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 
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6272 LC_MESSAGES 

6273 Determine the locale that should be used to affect the format and contents of 

6274 diagnostic messages written to standard error. 

6275 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

6276 ASYNCHRONOUS EVENTS 

6277 Default. 

6278 STDOUT 

6279 The standard output shall be the text from the input file modified as described in the 

6280 DESCRIPTION section. 

6281 STDERR 

6282 None. 

6283 OUTPUT FILES 

6284 None. 

6285 EXTENDED DESCRIPTION 

6286 None. 

6287 EXIT STATUS 

6288 The following exit values shall be returned: 

6289 0 All input files were output successfully. 

6290 >0 An error occurred. 

6291 CONSEQUENCES OF ERRORS 

6292 Default. 

6293 APPLICATION USAGE 

6294 None. 

6295 EXAMPLES 

6296 1. The following command: 

6297 asa file 

6298 permits the viewing of file (created by a program using FORTRAN-style carriage control 

6299 characters) on a terminal. 

6300 2. The following command: 

6301 a. out I asa | lp 

6302 formats the FORTRAN output of a.out and directs it to the printer. 

6303 RATIONALE 

6304 The asa utility is needed to map "standard" FORTRAN 77 output into a form acceptable to 

6305 contemporary printers. Usually, asa is used to pipe data to the Ip utility; see Ip. 

6306 This utility is generally used only by FORTRAN programs. The standard developers decided to 

6307 retain asa to avoid breaking the historical large base of FORTRAN applications that put 

6308 carriage-control characters in their output files. There is no requirement that a system have a 

6309 FORTRAN compiler in order to run applications that need asa. 

6310 Historical implementations have used an ASCII <form-feed> character in response to a 1 and an 

6311 ASCII <carriage-return> in response to a '+'. It is suggested that implementations treat 

6312 characters other than 0, 1, and ' + ' as <space> in the absence of any compelling reason to do 

6313 otherwise. However, the action is listed here as "unspecified", permitting an implementation to 
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6314 provide extensions to access fast multiple-line slewing and channel seeking in a non-portable 

6315 manner. 

6316 FUTURE DIRECTIONS 

6317 None. 

6318 SEE ALSO 

6319 fort77, Ip 

6320 CHANGE HISTORY 

6321 First released in Issue 4. 

6322 Issue 6 

6323 This utility is now marked as part of the FORTRAN Runtime Utilities option. 

6324 The normative text is reworded to avoid use of the term "must” for application requirements. 
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6325 NAME 

6326 at — execute commands at a later time 

6327 SYNOPSIS 

6328 UP at [— m] [—f file] [—q queuename] —t time_arg 

6329 at [—m] [—f file] [-q queuename] timespec . . . 

6330 at —r at_job_id . . . 

6331 at —1 —q queuename 

6332 at —1 [at_job_id . . .] 

6333 


6334 DESCRIPTION 

6335 The at utility shall read commands from standard input and group them together as an at-job, to 

6336 be executed at a later time. 


6337 The at-job shall be executed in a separate invocation of the shell, running in a separate process 

6338 group with no controlling terminal, except that the environment variables, current working 

6339 directory, file creation mask, and other implementation-dependent execution-time attributes in 

6340 effect when the at utility is executed shall be retained and used when the at-job is executed. 

6341 When the at-job is submitted, the at_job_id and scheduled time shall be written to standard error. 

6342 The at_job_id is an identifier that shall be a string consisting solely of alphanumeric characters 

6343 and the period character. The at_job_id shall be assigned by the system when the job is scheduled 

6344 such that it uniquely identifies a particular job. 

6345 User notification and the processing of the job's standard output and standard error are 

6346 described under the -m option. 

6347 xsi Users are permitted to use at if their name appears in the file /usr/lib/cron/at.allow. If that file 

6348 does not exist, the file /usr/lib/cron/at.deny is checked to determine whether the user should be 

6349 denied access to at. If neither file exists, only a process with the appropriate privileges is 

6350 allowed to submit a job. If only at.deny exists and is empty, global usage is permitted. The 

6351 at.allow and at.deny files consist of one user name per line. 


6352 OPTIONS 

6353 The at utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

6354 Section 12.2, Utility Syntax Guidelines. I 


6355 


The following options shall be supported: 


6356 

6357 


-f file Specify the path name of a file to be used as the source of the at-job, instead of 

standard input. 


6358 -1 

6359 

6360 


(The letter ell.) Report all jobs scheduled for the invoking user if no at_job_id 
operands are specified. If at_job_id s are specified, report only information for these 
jobs. The output shall be written to standard output. 


6361 

6362 

6363 

6364 


-m Send mail to the invoking user after the at-job has run, announcing its completion. 

Standard output and standard error produced by the at-job shall be mailed to the 
user as well, unless redirected elsewhere. Mail shall be sent even if the job 
produces no output. 


6365 

6366 MAN 

6367 

6368 


If -m is not used, the job's standard output and standard error shall be provided to 
the user by means of mail, unless they are redirected elsewhere; if there is no such 
output to provide, the implementation need not notify the user of the job's 
completion. 
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6369 

6370 

6371 

6372 

6373 

6374 

6375 


-q queuename 

Specify in which queue to schedule a job for submission. When used with the -1 I 
option, limit the search to that particular queue. By default, at-jobs shall be 
scheduled in queue a. In contrast, queue b shall be reserved for batch jobs; see 
batch. The meanings of all other queuename s are implementation-dependent. If -q I 
is specified along with either of the -t time_arg or timespec arguments, the results I 
are unspecified. I 


6376 

6377 

6378 

6379 


-r Remove the jobs with the specified at_job_id operands that were previously 

scheduled by the at utility. I 

-t time_arg Submit the job to be run at the time specified by the time option-argument, which I 
the application shall ensure has the format as specified by the touch -t time utility. I 


6380 OPERANDS 

6381 The following operands shall be supported: 


6382 at_job_id The name reported by a previous invocation of the at utility at the time the job was 

6383 scheduled. 


6384 timespec Submit the job to be run at the date and time specified. All of the timespec operands 

6385 are interpreted as if they were separated by <space> characters and concatenated, 

6386 and shall be parsed as described in the grammar at the end of this section. The date 

6387 and time shall be interpreted as being in the timezone of the user (as determined 

6388 by the TZ variable), unless a timezone name appears as part of time, below. 

6389 In the POSIX locale, the following describes the three parts of the time 

6390 specification string. All of the values from the LC_TIME categories in the POSIX 

6391 locale shall be recognized in a case-insensitive manner. 


6392 

6393 

6394 

6395 

6396 

6397 

6398 

6399 

6400 

6401 

6402 

6403 


time The time can be specified as one, two, or four digits. One-digit and 

two-digit numbers shall be taken to be hours; four-digit numbers to 
be hours and minutes. The time can alternatively be specified as two 
numbers separated by a colon, meaning hour.minute. An AM/PM 
indication (one of the values from the am_pm keywords in the 
LC_TIME locale category) can follow the time; otherwise, a 24-hour 
clock time shall be understood. A timezone name can also follow to 
further qualify the time. The acceptable timezone names are 
implementation-dependent, except that they shall be case-insensitive 
and the string utc is supported to indicate the time is in Coordinated 
Universal Time. In the POSIX locale, the time field can also be one of 
the following tokens: 


6404 

midnight 

6405 

noon 

6406 

now 

6407 


6408 


6409 



Indicates the time 12:00 am (00:00). 

Indicates the time 12:00 pm. 

Indicates the current day and time. Invoking at <now> 
shall submit an at-job for potentially immediate 
execution (that is, subject only to unspecified 
scheduling delays). 


6410 

6411 

6412 

6413 

6414 

6415 


date An optional date can be specified as either a month name (one of the 

values from the mon or abmon keywords in the LC_TIME locale 
category) followed by a day number (and possibly year number 
preceded by a comma), or a day of the week (one of the values from 
the day or abday keywords in the LC_TIME locale category). In the 
POSIX locale, two special days shall be recognized: 
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6416 

6417 


today Indicates the current day. 

tomorrow Indicates the day following the current day. 


6418 

6419 

6420 

6421 


If no date is given, today shall be assumed if the given time is greater 
than the current time, and tomorrow shall be assumed if it is less. If 
the given month is less than the current month (and no year is given), 
next year shall be assumed. 


6422 

6423 

6424 

6425 

6426 


increment The optional incremeiit shall be a number preceded by a plus sign 
(' +') and suffixed by one of the following: minutes, hours, days, 
weeks, months, or years. (The singular forms shall be also 
accepted.) The keyword next shall be equivalent to an increment 
number of +1. For example, the following are equivalent commands: 


6427 

6428 


at 2pm + 1 week 
at 2pm next week 


6429 The following grammar describes the precise format of timespec in the POSIX locale. The general 

6430 conventions for this style of grammar are described in Section 1.10 on page 24. This formal 

6431 syntax shall take precedence over the preceding text syntax description. The longest possible 

6432 token or delimiter shall be recognized at a given point. When used in a timespec, white space 

6433 shall also delimit tokens. 


6434 

6435 

6436 

6437 

6438 

6439 

6440 

6441 

6442 

6443 


%token hr24clock_hr_min 
%token hr24clock_hour 
/* 

A hr24clock_hr_min is a one, two, or four-digit number. A one-digit 
or two-digit number constitutes a hr24clock_hour. A hr24clock_hour 
may be any of the single digits 0-9, or may be double digits, ranging 
from 00-23. If a hr24clock_hr_min is a four digit number, the 
first two digits shall be a valid hr24clock_hour, while the last two 
represent the number of minutes, from 00-59. 


6444 

6445 

6446 

6447 

6448 

6449 

6450 

6451 

6452 

6453 

6454 


%token wallclock_hr_min 
%token wallclock_hour 
/* 

A wallclock_hr_min is a one, two-digit, or four-digit number. 
A one-digit or two-digit number constitutes a wallclock_hour. 
A wallclock_hour may be any of the single digits 1-9, or may 
be double digits, ranging from 01-12. If a wallclock_hr_min 
is a four-digit number, the first two digits shall be a valid 
wallclock_hour, while the last two represent the number of 
minutes, from 00-59. 


6455 %token minute 

6456 / * 

6457 A minute is a one or two-digit number whose values can be 0-9 

6458 or 00-5 9. 

6459 * / 


6460 

6461 

6462 

6463 


%token day_number 
/* 

A day_number is a number in the range appropriate for the particular 
month and year specified by month_name and year_number, respectively. 
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6464 If no year_number is given, the current year is assumed if the given 

6465 date and time are later this year. If no year_number is given and 

6466 the date and time have already occurred this year and the month is 

6467 not the current month, next year is the assumed year. 

6468 * / 

6469 %token year_number 

6470 / * 

6471 A year_number is a four-digit number representing the year A.D., in 

6472 which the at_job is to be run. 

6473 * / 

6474 %token inc_number 

6475 / * 

6476 The inc_number is the number of times the succeeding increment 

6477 period is to be added to the specified date and time. 

6478 * / 

6479 %token timezone_name 

6480 / * 

6481 The name of an optional timezone suffix to the time field, in an 

6482 implementation-dependent format. 

6483 * / 

6484 %token month_name 

6485 / * 

6486 One of the values from the mon or abmon keywords in the LC_TIME 

6487 locale category. 

6488 * / 

6489 %token day_of_week 

6490 / * 

6491 One of the values from the day or abday keywords in the LC_TIME 

6492 locale category. 

6493 * / 

6494 % token am_pm 

6495 / * 

6496 One of the values from the am_pm keyword in the LC_TIME locale 

6497 category. 

6498 * / 

6499 %start timespec 


6500 

"6 "5 


6501 

timespec 

: time 

6502 


| time date 

6503 


| time increment 

6504 


| time date increment 

6505 


| nowspec 

6506 


r 

6507 

nowspec 

: "now" 

6508 


| "now" increment 

6509 


f 

6510 

time 

: hr24clock_hr_min 

6511 


| hr24clock_hr_min timezone_name 
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6512 

6513 

6514 

6515 

6516 

6517 

6518 

6519 

6520 


| hr24clock_hour ":" minute 
| hr24clock_hour ":" minute timezone_name 
I wallclock_hr_min am_pm 
I wallclock_hr_min am_pm timezone_name 
I wallclock_hour ":" minute am_pm 
I wallclock_hour ":" minute am_pm timezone_name 
| "noon" 

| "midnight" 


6521 

6522 

6523 

6524 

6525 

6526 


date 


: month_name day_number 

| month_name day_number year_number 

I day_of_week 
I "today" 

I "tomorrow" 


6527 increment : "+" inc_number inc_period 

6528 I "next" inc_period 

6529 ; 


6530 

6531 

6532 

6533 

6534 

6535 

6536 


inc_period 


: "minute" | "minutes" 
| "hour" | "hours" 

I "day" | "days" 

| "week" | "weeks" 

| "month" | "months" 

I "year" | "years" 


6537 STDIN 

6538 The standard input shall be a text file consisting of commands acceptable to the shell command I 

6539 language described in Chapter 2 on page 35. The standard input shall only be used if no -f file 

6540 option is specified. 

6541 INPUT FILES 

6542 See the STDIN section. 


6543 xsi The text files /usr/lib/cron/at.allow and /usr/lib/cron/at.deny contain user names, one per line, of 

6544 users who are, respectively, authorized or denied access to the at and batch utilities. 


6545 ENVIRONMENT VARIABLES 

6546 The following environment variables shall affect the execution of at: 


6547 

6548 

6549 

6550 

6551 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


6552 

6553 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


6554 

6555 

6556 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


6557 LC_MESSAGES 

6558 Determine the locale that should be used to affect the format and contents of 
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6559 diagnostic messages written to standard error and informative messages written to 

6560 standard output. 

6561 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


6562 LC_TIME Determine the format and contents for date and time strings written and accepted 

6563 by at. 


6564 

6565 

6566 

6567 

6568 


SHELL Determine a name of a command interpreter to be used to invoke the at-job. If the 
variable is unset or null, sh shall be used. If it is set to a value other than a name for 
sh, the implementation shall do one of the following: use that shell; use sh; use the 
login shell from the user database; or any of the preceding accompanied by a 
warning diagnostic about which was chosen. 


6569 

6570 

6571 

6572 

6573 


TZ Determine the timezone. The job shall be submitted for execution at the time 

specified by timespec or -t time relative to the timezone specified by the TZ 
variable. If timespec specifies a timezone, it shall override TZ. If timespec does not 
specify a timezone and TZ is unset or null, an unspecified default timezone shall 
be used. 


6574 ASYNCHRONOUS EVENTS 

6575 Default. 


6576 STDOUT 

6577 When standard input is a terminal, prompts of unspecified format for each line of the user input 

6578 described in the STDIN section may be written to standard output. 

6579 In the POSIX locale, the following shall be written to the standard output for each job when jobs 

6580 are listed in response to the -1 option: 

6581 "%s\t%s\n", at_job_id, <date> 

6582 where date shall be equivalent in format to the output of: 

6583 date +"%a %b %e %T %Y" 

6584 The date and time written shall be adjusted so that they appear in the timezone of the user (as 

6585 determined by the TZ variable). 

6586 STDERR 

6587 In the POSIX locale, the following shall be written to standard error when a job has been I 

6588 successfully submitted: I 

6589 "job %s at %s\n", at_job_id, <date> 

6590 where date has the same format as is described in the STDOUT section. Neither this, nor warning 

6591 messages concerning the selection of the command interpreter, shall be considered a diagnostic 

6592 that changes the exit status. 

6593 Diagnostic messages, if any, shall be written to standard error. 

6594 OUTPUT FILES 

6595 None. 


6596 EXTENDED DESCRIPTION 

6597 None. 


6598 EXIT STATUS 

6599 The following exit values shall be returned: 

6600 0 The at utility successfully submitted, removed, or listed a job or jobs. 
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6601 >0 An error occurred. 


6602 CONSEQUENCES OF ERRORS 

6603 The job shall not be scheduled, removed, or listed. 


6604 APPLICATION USAGE 

6605 The format of the at command line shown here is guaranteed only for the POSIX locale. Other 

6606 cultures may be supported with substantially different interfaces, although implementations are 

6607 encouraged to provide comparable levels of functionality. 

6608 Since the commands run in a separate shell invocation, running in a separate process group with 

6609 no controlling terminal, open file descriptors, traps, and priority inherited from the invoking 

6610 environment are lost. 

6611 Some implementations do not allow substitution of different shells using SHELL. System V 

6612 systems, for example, have used the login shell value for the user in /etc/passwd. To select 

6613 reliably another command interpreter, the user must include it as part of the script, such as: 

6614 $ at 1800 

6615 myshell myscript 

6616 job ... at ... 

6617 $ 

6618 Application writers should note that this utility need not be provided on systems that do not 

6619 support the User Portability Utilities option. 

6620 EXAMPLES 


6621 


1. This sequence can be used at a terminal: 


6622 

6623 

6624 


at —m 0730 tomorrow 
sort < file >outfile 
EOT 


6625 

6626 


2. This sequence, which demonstrates redirecting standard error to a pipe, is useful in a 
command procedure (the sequence of output redirection specifications is significant): 


6627 

6628 
6629 


at now + 1 hour <<! 

diff filel file2 2>&1 >outfile I mailx mygroup 


6630 

6631 

6632 


3. To have a job reschedule itself, at can be invoked from within the at-job. For example, this 
daily processing script named my.daily runs every day (although crontab is a more 
appropriate vehicle for such work): 


6633 

6634 

6635 


# my.daily runs every day 

daily processing 

at now tomorrow < my.daily 


6636 

6637 


4. The spacing of the three portions of the POSIX locale timespec is quite flexible as long as 
there are no ambiguities. Examples of various times and operand presentation include: 


6638 

6639 

6640 

6641 

6642 

6643 

6644 


at 0815am Jan 24 
at 8 :15amjan24 
at now "+ lday" 
at 5 pm FRIday 
at ' 17 
utc+ 

30minutes' 
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6645 RATIONALE 

6646 The at utility reads from standard input the commands to be executed at a later time. It may be 

6647 useful to redirect standard output and standard error within the specified commands. 

6648 The -t time option was added as a new capability to support an internationalized way of 

6649 specifying a time for execution of the submitted job. 

6650 Early proposals added a "jobname" concept as a way of giving submitted jobs names that are 

6651 meaningful to the user submitting them. The historical, system-specified at_job_id gives no 

6652 indication of what the job is. Upon further reflection, it was decided that the benefit of this was 

6653 not worth the change in historical interface. It is anticipated that considerably more 

6654 sophisticated ways of controlling background or batch work will be the subject of a future 

6655 version of this volume of IEEE Std. 1003.1-200x. 

6656 The -q option historically has been an undocumented option, used mainly by the batch utility. 

6657 The System V -m option was added to provide a method for informing users that an at-job had 

6658 completed. Otherwise, users are only informed when output to standard error or standard 

6659 output are not redirected. 

6660 The behavior of at <now> was changed in an early proposal from being unspecified to 

6661 submitting a job for potentially immediate execution. Historical BSD at implementations 

6662 support this. Historical System V implementations give an error in that case, but a change to the 

6663 System V versions should have no backwards compatibility ramifications. 

6664 On BSD-based systems, a -u user option has allowed those with appropriate privileges to access 

6665 the work of other users. Since this is primarily a system administration feature and is not 

6666 universally implemented, it has been omitted. Similarly, a specification for the output format for 

6667 user with appropriate privileges viewing the queues of other users has been omitted. 

6668 The -{file option from System V is used instead of the BSD method of using the last operand as 

6669 the path name. The BSD method is ambiguous—does: 

6670 at 12 00 friday 

6671 mean the same thing if there is a file named friday in the current directory? 

6672 The at_job_id is composed of a limited character set in historical practice, and it is mandated here 

6673 to invalidate systems that might try using characters that require shell quoting or that could not 

6674 be easily parsed by shell scripts. 

6675 The at utility varies between System V and BSD systems in the way timezones are used. On 

6676 System V systems, the TZ variable affects the at-job submission times and the times displayed 

6677 for the user. On BSD systems, TZ is not taken into account. The BSD behavior is easily achieved 

6678 with the current specification. If the user wishes to have the timezone default to that of the 

6679 system, they merely need to issue the at command immediately following an unsetting or null 

6680 assignment to TZ. For example: 

6681 TZ= at noon . . . 

6682 gives the desired BSD result. 

6683 While the yacc-li ke grammar specified in the OPERANDS section is lexically unambiguous with 

6684 respect to the digit strings, a lexical analyzer would probably be written to look for and return 

6685 digit strings in those cases. The parser could then check whether the digit string returned is a 

6686 valid day_nnmber , year_number , and so on, based on the context. 
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6687 FUTURE DIRECTIONS 

6688 None. 

6689 SEE ALSO 

6690 batch, crontab 

6691 CHANGE HISTORY 

6692 First released in Issue 2. 

6693 Issue 4 

6694 Aligned with the ISO/IEC 9945-2:1993 standard. 

6695 Issue 6 

6696 This utility is now marked as part of the User Portability Utilities option. 

6697 The following new requirements on POSIX implementations derive from alignment with the 

6698 Single UNIX Specification: 

6699 • If -m is not used, the job's standard output and standard error are provided to the user by 

6700 mail. 

6701 The effects of using the -q and -t options as defined in the IEEE P1003.2b draft standard are I 

6702 specified. I 

6703 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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6704 NAME 

6705 awk — pattern scanning and processing language 

6706 SYNOPSIS 

6707 awk [—F ERE] [—v assignment] . . . program [argument . . . ] 

6708 awk [—F ERE] —f prog file . . . [—v assignment] . . . [argument . . .] 

6709 DESCRIPTION 

6710 The azvk utility shall execute programs written in the azvk programming language, which is I 

6711 specialized for textual data manipulation. An azvk program is a sequence of patterns and 

6712 corresponding actions. When input is read that matches a pattern, the action associated with 

6713 that pattern is carried out. 

6714 Input shall be interpreted as a sequence of records. By default, a record is a line, but this can be 

6715 changed by using the RS built-in variable. Each record of input shall be matched in turn against 

6716 each pattern in the program. For each pattern matched, the associated action shall be executed. 

6717 The azvk utility shall interpret each input record as a sequence of fields where, by default, a field 

6718 is a string of non-<blank> characters. This default white-space field delimiter can be changed by 

6719 using the FS built-in variable or the -F ERE. The azvk utility shall denote the first field in a 

6720 record $1, the second $2, and so on. The symbol $0 shall refer to the entire record; setting any 

6721 other field causes the re-evaluation of $0. Assigning to $0 shall reset the values of all other fields 

6722 and the NF built-in variable. 


6723 OPTIONS 

6724 The azvk utility shall conform to the System Interface Definitions volume of I 

6725 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

6726 The following options shall be supported: 


6727 -F ERE Define the input field separator to be the extended regular expression ERE , before 

6728 any input is read; see Regular Expressions on page 195. 


6729 

6730 

6731 

6732 


-f progfile Specify the path name of the file progfile containing an azvk program. If multiple 
instances of this option are specified, the concatenation of the files specified as 
progfile in the order specified shall be the azvk program. The azvk program can 
alternatively be specified in the command line as a single argument. 


6733 - v ass ign men t 

6734 The application shall ensure that the assignment argument is in the same form as an I 

6735 assignment operand. The specified variable assignment shall occur prior to 

6736 executing the azvk program, including the actions associated with BEGIN patterns 

6737 (if any). Multiple occurrences of this option can be specified. 


6738 OPERANDS 

6739 The following operands shall be supported: 


6740 

6741 

6742 

6743 


program If no -f option is specified, the first operand to azvk shall be the text of the azvk 
program. The application shall supply the program operand as a single argument to 
azvk. If the text does not end in a <newline> character, azvk shall interpret the text 
as if it did. 


6744 


argument Either of the following two types of argument can be intermixed: 


6745 

6746 

6747 

6748 


file A path name of a file that contains the input to be read, which is 

matched against the set of patterns in the program. If no file operands 
are specified, or if a file operand is , the standard input shall be 
used. 
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6749 

6750 

6751 

6752 

6753 

6754 

6755 

6756 

6757 

6758 

6759 

6760 

6761 

6762 

6763 

6764 

6765 

6766 

6767 

6768 

6769 

6770 

6771 


assignment An operand that begins with an underscore or alphabetic character 

from the portable character set (see the table in the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable I 
Character Set), followed by a sequence of underscores, digits, and I 
alphabetics from the portable character set, followed by the ' = ' I 
character, shall specify a variable assignment rather than a path I 
name. The characters before the ' =' represent the name of an awk I 
variable; if that name is an awk reserved word (see Grammar on page 
204) the behavior is undefined. The characters following the equal 
sign shall be interpreted as if they appeared in the awk program 
preceded and followed by a double-quote (' "') character, as a 
STRING token (see Grammar on page 204), except that if the last 
character is an unescaped backslash, it shall be interpreted as a literal 
backslash rather than as the first character of the sequence " \"". 
The variable shall be assigned the value of that STRING token and, I 
if appropriate, shall be considered a numeric string (see Expressions I 
in awk on page 190), the variable shall also be assigned its numeric 
value. Each such variable assignment shall occur just prior to the 
processing of the following file, if any. Thus, an assignment before 
the first file argument shall be executed after the BEGIN actions (if 
any), while an assignment after the last file argument shall occur 
before the END actions (if any). If there are no file arguments, 
assignments shall be executed before processing the standard input. 


6772 STDIN 

6773 The standard input shall be used only if no file operands are specified, or if a file operand is ' ; I 

6774 see the INPUT FILES section. If the awk program contains no actions and no patterns, but is I 

6775 otherwise a valid awk program, standard input and any file operands shall not be read and awk I 

6776 shall exit with a return status of zero. I 


6777 INPUT FILES 

6778 Input files to the awk program from any of the following sources shall be text files: 

6779 • Any file operands or their equivalents, achieved by modifying the awk variables ARGV and 

6780 ARGC 


6781 • Standard input in the absence of any file operands 

6782 • Arguments to the getline function 

6783 Whether the variable RS is set to a value other than a <newline> character or not, for these files, 

6784 implementations shall support records terminated with the specified separator up to 

6785 |LINE_MAX} bytes and may support longer records. 

6786 If -f progfile is specified, the application shall ensure that the files named by each of the progfile I 

6787 option-arguments are text files containing an awk program. I 


6788 ENVIRONMENT VARIABLES 

6789 The following environment variables shall affect the execution of awk: 


6790 

6791 

6792 

6793 

6794 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 
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6795 LC_ALL If set to a non-empty string value, override the values of all the other 

6796 internationalization variables. 

6797 LC_COLLATE 

6798 Determine the locale for the behavior of ranges, equivalence classes, and multi- 

6799 character collating elements within regular expressions and in comparisons of 

6800 string values. 

6801 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

6802 characters (for example, single-byte as opposed to multi-byte characters in 

6803 arguments and input files), the behavior of character classes within regular 

6804 expressions, the identification of characters as letters, and the mapping of 

6805 uppercase and lowercase characters for the toupper and tolower functions. 

6806 LC_MESSAGES 

6807 Determine the locale that should be used to affect the format and contents of 

6808 diagnostic messages written to standard error. 

6809 LCJNUMERIC 

6810 Determine the radix character used when interpreting numeric input, performing 

6811 conversions between numeric and string values, and formatting numeric output. 

6812 Regardless of locale, the period character (the decimal-point character of the 

6813 POSIX locale) is the decimal-point character recognized in processing awk I 

6814 programs (including assignments in command line arguments). I 

6815 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

6816 PATH Determine the search path when looking for commands executed by system(expr), I 

6817 or input and output pipes; see the System Interface Definitions volume of I 

6818 IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

6819 In addition, all environment variables shall be visible via the azvk variable ENVIRON. 

6820 ASYNCHRONOUS EVENTS 

6821 Default. 

6822 STDOUT 

6823 The nature of the output files depends on the azvk program. 

6824 STDERR 

6825 Used only for diagnostic messages. 

6826 OUTPUT FILES 

6827 The nature of the output files depends on the azvk program. 

6828 EXTENDED DESCRIPTION 


6829 Overall Program Structure 

6830 An azvk program is composed of pairs of the form: 

6831 pattern { action } 

6832 Either the pattern or the action (including the enclosing brace characters) can be omitted. 

6833 A missing pattern shall match any record of input, and a missing action shall be equivalent to: I 

6834 { print } I 

6835 Execution of the azvk program shall start by first executing the actions associated with all BEGIN I 

6836 patterns in the order they occur in the program. Then each file operand (or standard input if no 
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6837 files were specified) shall be processed in turn by reading data from the file until a record 

6838 separator is seen (<newline> by default). Before the first reference to a field in the record is 

6839 evaluated, the record shall be split into fields, according to the rules in Regular Expressions on 

6840 page 195, using the value of FS that was current at the time the record was read. Each pattern in 

6841 the program then shall be evaluated in the order of occurrence, and the action associated with 

6842 each pattern that matches the current record executed. The action for a matching pattern shall be 

6843 executed before evaluating subsequent patterns. Finally, the actions associated with all END 

6844 patterns shall be executed in the order they occur in the program. 

6845 Expressions in awk 

6846 Expressions describe computations used in patterns and actions. In the following table, valid 

6847 expression operations are given in groups from highest precedence first to lowest precedence 

6848 last, with equal-precedence operators grouped between horizontal lines. In expression 

6849 evaluation, where the grammar is formally ambiguous, higher precedence operators shall be 

6850 evaluated before lower precedence operators. In this table expr, exprl, exprl, and expr3 represent 

6851 any expression, while lvalue represents any entity that can be assigned to (that is, on the left side 

6852 of an assignment operator). The precise syntax of expressions is given in Grammar on page 204. 

6853 

6854 

6855 

6856 

6857 

6858 

6859 

6860 
6861 
6862 

6863 

6864 

6865 

6866 

6867 

6868 

6869 

6870 

6871 

6872 

6873 

6874 

6875 

6876 

6877 

6878 

6879 

6880 


Table 4-1 Expressions in Decreasing Precedence in awk 


Syntax 

Name 

Type of Result 

Associativity 

( expr ) 

Grouping 

Type of expr 

N/A 

$expr 

Field reference 

String 

N/A 

++ lvalue 

Pre-increment 

Numeric 

N/A 

— lvalue 

Pre-decrement 

Numeric 

N/A 

lvalue ++ 

Post-increment 

Numeric 

N/A 

lvalue — 

Post-decrement 

Numeric 

N/A 

expr " expr 

Exponentiation 

Numeric 

Right 

! expr 

Logical not 

Numeric 

N/A 

+ expr 

Unary plus 

Numeric 

N/A 

— expr 

Unary minus 

Numeric 

N/A 

expr * expr 

Multiplication 

Numeric 

Left 

expr / expr 

Division 

Numeric 

Left 

expr % expr 

Modulus 

Numeric 

Left 

expr + expr 

Addition 

Numeric 

Left 

expr — expr 

Subtraction 

Numeric 

Left 

expr expr 

String concatenation 

String 

Left 

expr < expr 

Less than 

Numeric 

None 

expr <= expr 

Less than or equal to 

Numeric 

None 

expr != expr 

Not equal to 

Numeric 

None 

expr == expr 

Equal to 

Numeric 

None 

expr > expr 

Greater than 

Numeric 

None 

expr >= expr 

Greater than or equal to 

Numeric 

None 

expr ~ expr 

ERE match 

Numeric 

None 

expr !~ expr 

ERE non-match 

Numeric 

None 

expr in array 

Array membership 

Numeric 

Left 
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6881 


6882 

Syntax 

Name 

Type of Result 

Associativity 

6883 

6884 

( index ) in array 

Multi-dimension array 
membership 

Numeric 

Left 

6885 

expr & & expr 

Logical AND 

Numeric 

Left 

6886 

expr || expr 

Logical OR 

Numeric 

Left 

6887 

6888 

exprl ? expr2 : expr3 

Conditional expression 

Type of selected 

expr2 or expr3 

Right 

6889 

lvalue "= expr 

Exponentiation assignment 

Numeric 

Right 

6890 

lvalue %= expr 

Modulus assignment 

Numeric 

Right 

6891 

lvalue *= expr 

Multiplication assignment 

Numeric 

Right 

6892 

lvalue /= expr 

Division assignment 

Numeric 

Right 

6893 

lvalue += expr 

Addition assignment 

Numeric 

Right 

6894 

lvalue —= expr 

Subtraction assignment 

Numeric 

Right 

6895 

lvalue = expr 

Assignment 

Type of expr 

Right 


6896 Each expression shall have either a string value, a numeric value, or both. Except as stated for 

6897 specific contexts, the value of an expression shall be implicitly converted to the type needed for 

6898 the context in which it is used. A string value shall be converted to a numeric value by the 

6899 equivalent of the following calls to functions defined by the ISO C standard: 


6900 setlocale (LC_NUMERIC, 

6901 numeric_value = atof (string_value) ; 


6902 A numeric value that is exactly equal to the value of an integer shall be converted to a string by 

6903 the equivalent of a call to the sprintf function (see String Functions on page 201) with the string 

6904 "%d" as the/mf argument and the numeric value being converted as the first and only expr 

6905 argument. Any other numeric value shall be converted to a string by the equivalent of a call to 

6906 the sprintf function with the value of the variable CONVFMT as the fmt argument and the 

6907 numeric value being converted as the first and only expr argument. The result of the conversion 

6908 is unspecified if the value of CONVFMT is not a floating-point format specification. This 

6909 volume of IEEE Std. 1003.1-200x specifies no explicit conversions between numbers and strings. 

6910 An application can force an expression to be treated as a number by adding zero to it, or can 

6911 force it to be treated as a string by concatenating the null string (" ") to it. 


6912 

6913 

6914 

6915 

6916 

6917 

6918 

6919 

6920 

6921 

6922 

6923 


A string value shall be considered a numeric string if it comes from one of the following: 

1. Field variables 

2. Input from the getline () function 

3. FILENAME 

4. ARGV array elements 

5. ENVIRON array elements 

6. Array elements created by the split () function 

7. A command line variable assignment 

8. Variable assignment from another numeric string variable 

and after all the following conversions have been applied, the resulting string would lexically be 
recognized as a NUMBER token as described by the lexical conventions in Grammar on page 
204: 


6924 • All leading and trailing <blank>s are discarded 
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6925 

6926 

6927 

6928 

6929 

6930 

6931 

6932 

6933 

6934 

6935 

6936 

6937 

6938 

6939 

6940 

6941 

6942 

6943 

6944 

6945 

6946 

6947 

6948 

6949 

6950 

6951 

6952 

6953 

6954 

6955 

6956 

6957 

6958 

6959 

6960 

6961 


• If the first non-<blank> character is ' +' or ' -', it is discarded I 

• Changing each occurrence of the decimal point character from the current locale to a period I 

If a ' character is ignored in the preceding description, the numeric value of the numeric string I 
shall be the negation of the numeric value of the recognized NUMBER token. Otherwise, the 
numeric value of the numeric string shall be the numeric value of the recognized NUMBER 
token. Whether or not a string is a numeric string shall be relevant only in contexts where that 
term is used in this section. 

When an expression is used in a Boolean context, if it has a numeric value, a value of zero shall 
be treated as false and any other value shall be treated as true. Otherwise, a string value of the 
null string shall be treated as false and any other value shall be treated as true. A Boolean 
context shall be one of the following: 

• The first subexpression of a conditional expression 

• An expression operated on by logical NOT, logical AND, or logical OR 

• The second expression of a for statement 

• The expression of an if statement 

• The expression of the while clause in either a while or do.. .while statement 

• An expression used as a pattern (as in Overall Program Structure) 

All arithmetic shall follow the semantics of floating-point arithmetic as specified by the ISO C 
standard. 

The value of the expression: 

exprl ' expr2 

shall be equivalent to the value returned by the ISO C standard function call: 

pow ( exprl, expr2) 

The expression: 
lvalue " = expr 

shall be equivalent to the ISO C standard expression: 

lvalue = pow (lvalue, expr) 

except that lvalue shall be evaluated only once. The value of the expression: 

exprl % expr2 

shall be equivalent to the value returned by the ISO C standard function call: 

fmod( exprl, expr2) 

The expression: 
lvalue %= expr 

shall be equivalent to the ISO C standard expression: 

lvalue = fmod {lvalue, expr) 

except that lvalue shall be evaluated only once. 

Variables and fields shall be set by the assignment statement: 
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6962 lvalue = expression 

6963 and the type of expression shall determine the resulting variable type. The assignment includes 

6964 the arithmetic assignments ("+=", "—") all of which 

6965 shall produce a numeric result. The left-hand side of an assignment and the target of increment 

6966 and decrement operators can be one of a variable, an array with index, or a field selector. 

6967 The awk language supplies arrays that are used for storing numbers or strings. Arrays need not 

6968 be declared. They shall initially be empty, and their sizes shall change dynamically. The 

6969 subscripts, or element identifiers, are strings, providing a type of associative array capability. An 

6970 array name followed by a subscript within square brackets can be used as an lvalue and thus as 

6971 an expression, as described in the grammar; see Grammar on page 204. Unsubscripted array 

6972 names can be used in only the following contexts: 

6973 • A parameter in a function definition or function call 

6974 • The NAME token following any use of the keyword in as specified in the grammar (see 

6975 Grammar on page 204); if the name used in this context is not an array name, the behavior is 

6976 undefined 

6977 A valid array index shall consist of one or more comma-separated expressions, similar to the way 

6978 in which multi-dimensional arrays are indexed in some programming languages. Because awk 

6979 arrays are really one-dimensional, such a comma-separated list shall be converted to a single 

6980 string by concatenating the string values of the separate expressions, each separated from the 

6981 other by the value of the SUB SEP variable. Thus, the following two index operations shall be 

6982 equivalent: 

6983 var[exprl, expr2, . . . exprn ] 

6984 var[exprl SUBSEP expr2 SUBSEP . . . SUBSEP exprn] 

6985 The application shall ensure that a multi-dimensioned index used with the in operator is I 

6986 parenthesized. The in operator, which tests for the existence of a particular array element, shall I 

6987 not cause that element to exist. Any other reference to a nonexistent array element shall 

6988 automatically create it. 

6989 Comparisons (with the '<', "<=", "!=", "==", ' >', and ">=" operators) shall be made I 

6990 numerically if both operands are numeric, if one is numeric and the other has a string value that I 

6991 is a numeric string, or if one is numeric and the other has the uninitialized value. Otherwise, I 

6992 operands shall be converted to strings as required and a string comparison shall be made using I 

6993 the locale-specific collation sequence. The value of the comparison expression shall be 1 if the I 

6994 relation is true, or 0 if the relation is false. I 

6995 Variables and Special Variables 

6996 Variables can be used in an awk program by referencing them. With the exception of function I 

6997 parameters (see User-Defined Functions on page 203), they are not explicitly declared. Function I 

6998 parameter names shall be local to the function; all other variable names shall be global. The same I 

6999 name shall not be used as both a function parameter name and as the name of a function or a I 

7000 special awk variable. The same name shall not be used both as a variable name with global scope I 

7001 and as the name of a function. The same name shall not be used within the same scope both as a I 

7002 scalar variable and as an array. Uninitialized variables, including scalar variables, array I 

7003 elements, and field variables, shall have an uninitialized value. An uninitialized value shall have I 

7004 both a numeric value of zero and a string value of the empty string. Evaluation of variables with I 

7005 an uninitialized value, to either string or numeric, shall be determined by the context in which I 

7006 they are used. I 
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7007 Field variables shall be designated by a ' $' followed by a number or numerical expression. The 

7008 effect of the field number expression evaluating to anything other than a non-negative integer is 

7009 unspecified; uninitialized variables or string values need not be converted to numeric values in 

7010 this context. New field variables can be created by assigning a value to them. References to 

7011 nonexistent fields (that is, fields after $NF), shall evaluate to the uninitialized value. Such 

7012 references shall not create new fields. However, assigning to a nonexistent field (for example, 

7013 $(NF+2)=5) shall increase the value of NF; create any intervening fields with the uninitialized 

7014 value; and cause the value of $0 to be recomputed, with the fields being separated by the value 

7015 of OFS. Each field variable shall have a string value or an uninitialized value when created. 

7016 Field variables shall have the uninitialized value when created from $0 using FS and the variable 

7017 does not contain any characters. If appropriate, the field variable shall be considered a numeric 

7018 string (see Expressions in awk on page 190). 

7019 Implementations shall support the following other special variables that are set by awk: 


7020 

7021 

7022 


ARGC The number of elements in the ARGV array. 

ARGV An array of command line arguments, excluding options and the program 
argument, numbered from zero to ARGC-1. 


7023 

7024 

7025 

7026 

7027 

7028 

7029 


The arguments in ARGV can be modified or added to; ARGC can be altered. As 
each input file ends, awk shall treat the next non-null element of ARGV, up to the 
current value of ARGC-1, inclusive, as the name of the next input file. Thus, 
setting an element of ARGV to null means that it shall not be treated as an input 
file. The name indicates the standard input. If an argument matches the 
format of an assignment operand, this argument shall be treated as an assignment 
rather than a file argument. 


7030 CONVFMT The printf format for converting numbers to strings (except for output statements, 

7031 where OFMT is used); "% . 6g" by default. 


7032 

7033 

7034 

7035 

7036 

7037 

7038 


ENVIRON The variable ENVIRON is an array representing the value of the environment, as 
described in the exec functions defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x. The indices of the array shall be strings consisting of the 
names of the environment variables, and the value of each array element is a string 
consisting of the value of that variable. If appropriate, the environment variable I 
shall be considered a numeric string (see Expressions in awk on page 190), the I 
array element shall also have its numeric value. 


7039 

7040 

7041 

7042 

7043 

7044 


In all cases where the behavior of azuk is affected by environment variables 
(including the environment of any commands that awk executes via the system 
function or via pipeline redirections with the print statement, the printf statement, 
or the getline function), the environment used shall be the environment at the time 
awk began executing; it is implementation-dependent whether any modification of 
ENVIRON affects this environment. 


7045 

7046 

7047 


FILENAME A path name of the current input file. Inside a BEGIN action the value is 
undefined. Inside an END action the value is the name of the last input file 
processed. 


7048 

7049 

7050 


FNR The ordinal number of the current record in the current file. Inside a BEGIN action 

the value is zero. Inside an END action the value is the number of the last record 
processed in the last file processed. 


7051 FS 


Input field separator regular expression; a <space> character by default. 


7052 

7053 


NF 


The number of fields in the current record. Inside a BEGIN action, the use of NF is 
undefined unless a getline function without a var argument is executed 
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7054 

7055 

7056 


previously. Inside an END action, NF retains the value it had for the last record 
read, unless a subsequent redirected, getline function without a var argument is 
performed prior to entering the END action. 


7057 

7058 

7059 


NR The ordinal number of the current record from the start of input. Inside a BEGIN 

action the value is zero. Inside an END action the value is the number of the last 
record processed. 


7060 

7061 

7062 


OFMT The printf format for converting numbers to strings in output statements (see 
Output Statements on page 199); "% . 6g" by default. The result of the conversion 
is unspecified if the value of OFMT is not a floating-point format specification. 


7063 OFS The print statement output field separation; <space> by default. 

7064 ORS The print statement output record separator; a <newline> character by default. 

7065 RLENGTH The length of the string matched by the match function. 


7066 

7067 

7068 

7069 

7070 

7071 


RS The first character of the string value of RS is the input record separator; a 

<newline> character by default. If RS contains more than one character, the results 
are unspecified. If RS is null, then records are separated by sequences of one or 
more blank lines, leading or trailing blank lines do not result in empty records at 
the beginning or end of the input, and a <newline> character is always a field 
separator, no matter what the value of FS is. 


7072 RSTART The starting position of the string matched by the match function, numbering from 

7073 1. This is always equivalent to the return value of the match function. 


7074 SUB SEP The subscript separator string for multi-dimensional arrays; the default value is 

7075 implementation-dependent. 


7076 Regular Expressions 

7077 The azvk utility shall make use of the extended regular expression notation (see the System I 

7078 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.4, Extended Regular I 

7079 Expressions) except that it shall allow the use of C-language conventions for escaping special I 

7080 characters within the EREs, as specified in the table in the System Interface Definitions volume I 

7081 of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation ('W, ' \a', '\b', '\f', '\n', I 

7082 ' \r', ' \t', ' \v') and the following table; these escape sequences shall be recognized both 

7083 inside and outside bracket expressions. Note that records need not be separated by <newline> 

7084 characters and string constants can contain <newline> characters, so even the "\n" sequence is 

7085 valid in azvk EREs. Using a slash character within an ERE requires the escaping shown in the I 

7086 following table. I 


7087 


Table 4-2 Escape Sequences in azvk 
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7088 


7089 

7090 

Escape 

Sequence 

Description 

Meaning 

7091 

\" 

Backslash quotation-mark 

Quotation-mark character 

7092 

\/ 

Backslash slash 

Slash character 

7093 

\ddd 

A backslash character followed by the 

The character whose encoding is 

7094 


longest sequence of one, two, or three 

represented by the one, two, or three- 

7095 


octal-digit characters (01234567). If all 

digit octal integer. If the size of a byte 

7096 


of the digits are 0 (that is. 

on the system is greater than nine bits. 

7097 


representation of the NUL character). 

the valid escape sequence used to 

7098 


the behavior is undefined. 

represent a byte is implementation- 

7099 



dependent. Multi-byte characters 

7100 



require multiple, concatenated escape 

7101 



sequences of this type, including the 

7102 



leading ' \' for each byte. 

7103 

\c 

A backslash character followed by any 

Undefined 

7104 


character not described in this table or 


7105 


in the table in the System Interface 


7106 


Definitions volume of 


7107 


IEEE Std. 1003.1-200x, Chapter 5, File 


7108 


Format Notation (' \\', ' \a', ' \b', 


7109 


'\f', '\n', '\r', '\t', '\v') 



7110 A regular expression can be matched against a specific field or string by using one of the two 

7111 regular expression matching operators, ' ~' and " ! These operators shall interpret their 

7112 right-hand operand as a regular expression and their left-hand operand as a string. If the regular 

7113 expression matches the string, the ' ~' expression shall evaluate to a value of 1, and the "! ~ " 

7114 expression shall evaluate to a value of 0. (The regular expression matching operation is as I 

7115 defined by the term matched in the System Interface Definitions volume of I 

7116 IEEE Std. 1003.1-200x, Section 9.1, Regular Expression Definitions, where a match occurs on any I 

7117 part of the string unless the regular expression is limited with the circumflex or dollar sign 

7118 special characters.) If the regular expression does not match the string, the ' ~' expression shall 

7119 evaluate to a value of 0, and the " ! ~ " expression shall evaluate to a value of 1. If the right-hand 

7120 operand is any expression other than the lexical token ERE, the string value of the expression 

7121 shall be interpreted as an extended regular expression, including the escape conventions 

7122 described above. Note that these same escape conventions shall also be applied in determining 

7123 the value of a string literal (the lexical token STRING), and thus shall be applied a second time 

7124 when a string literal is used in this context. 

7125 When an ERE token appears as an expression in any context other than as the right-hand of the 

7126 ' ~' or " ! ~ " operator or as one of the built-in function arguments described below, the value of 

7127 the resulting expression shall be the equivalent of: 

7128 $0 ~ /ere/ 

7129 The ere argument to the gsub, match, sub functions, and the fs argument to the split function 

7130 (see String Functions on page 201) shall be interpreted as extended regular expressions. These 

7131 can be either ERE tokens or arbitrary expressions, and shall be interpreted in the same manner as 

7132 the right-hand side of the ' ~' or " ! ~" operator. 

7133 An extended regular expression can be used to separate fields by using the -F ERE option or by 

7134 assigning a string containing the expression to the built-in variable FS. The default value of the 

7135 FS variable shall be a single <space> character. The following describes FS behavior: 
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7136 

7137 

7138 

7139 

7140 

7141 

7142 

7143 

7144 


1. If FS is a null string, the behavior is unspecified. 

2. If FS is a single character: 

a. If FS is the <space> character, skip leading and trailing <blank> characters; fields 
shall be delimited by sets of one or more <blank> characters. 

b. Otherwise, if FS is any other character c, fields shall be delimited by each single 
occurrence of c. 

3. Otherwise, the string value of FS shall be considered to be an extended regular expression. 
Each occurrence of a sequence matching the extended regular expression shall delimit 
fields. 


7145 Except for the ' ~' and " ! ~ " operators, and in the gsub, match, split, and sub built-in functions, 

7146 ERE matching shall be based on input records; that is, record separator characters (the first 

7147 character of the value of the variable RS, <newline> by default) cannot be embedded in the 

7148 expression, and no expression shall match the record separator character. If the record separator 

7149 is not <newline>, <newline> characters embedded in the expression can be matched. For the 

7150 ' ~' and "! ~ " operators, and in those four built-in functions, ERE matching shall be based on 

7151 text strings; that is, any character (including <newline> and the record separator) can be 

7152 embedded in the pattern, and an appropriate pattern shall match any character. However, in all 

7153 awk ERE matching, the use of one or more NUL characters in the pattern, input record, or text 

7154 string produces undefined results. 


7155 Patterns 

7156 A pattern is any valid expression, a range specified by two expressions separated by comma, or 

7157 one of the two special patterns BEGIN or END. 

7158 Special Patterns 

7159 The awk utility shall recognize two special patterns, BEGIN and END. Each BEGIN pattern 

7160 shall be matched once and its associated action executed before the first record of input is read 

7161 (except possibly by use of the getline function—see Input/Output and General Functions on 

7162 P a g e 202—in a prior BEGIN action) and before command line assignment is done. Each END 

7163 pattern shall be matched once and its associated action executed after the last record of input has 

7164 been read. These two patterns shall have associated actions. 

7165 BEGIN and END shall not combine with other patterns. Multiple BEGIN and END patterns 

7166 shall be allowed. The actions associated with the BEGIN patterns shall be executed in the order 

7167 specified in the program, as are the END actions. An END pattern can precede a BEGIN pattern 

7168 in a program. 

7169 If an awk program consists of only actions with the pattern BEGIN, and the BEGIN action 

7170 contains no getline function, awk shall exit without reading its input when the last statement in 

7171 the last BEGIN action is executed. If an awk program consists of only actions with the pattern 

7172 END or only actions with the patterns BEGIN and END, the input shall be read before the 

7173 statements in the END actions are executed. 
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7174 Expression Patterns 

7175 An expression pattern shall be evaluated as if it were an expression in a Boolean context. If the 

7176 result is true, the pattern shall be considered to match, and the associated action (if any) shall be 

7177 executed. If the result is false, the action shall not be executed. 

7178 Pattern Ranges 

7179 A pattern range consists of two expressions separated by a comma; in this case, the action shall 

7180 be performed for all records between a match of the first expression and the following match of 

7181 the second expression, inclusive. At this point, the pattern range can be repeated starting at 

7182 input records subsequent to the end of the matched range. 

7183 Actions 

7184 An action is a sequence of statements as shown in the grammar in Grammar on page 204. Any 

7185 single statement can be replaced by a statement list enclosed in braces. The application shall I 

7186 ensure that statements in a statement list are separated by <newline> characters or semicolons, I 

7187 and are executed sequentially in the order that they appear. 

7188 The expression acting as the conditional in an if statement shall be evaluated and if it is non-zero 

7189 or non-null, the following statement shall be executed; otherwise, if else is present, the statement 

7190 following the else shall be executed. 

7191 The if, while, do. . .while, for, break, and continue statements are based on the ISO C standard, 

7192 except that the Boolean expressions shall be treated as described in Expressions in awk on page 

7193 190, and except in the case of: 

7194 for (variable in array) 

7195 which shall iterate, assigning each index of array to variable in an unspecified order. The results of 

7196 adding new elements to array within such a for loop are undefined. If a break or continue 

7197 statement occurs outside of a loop, the behavior is undefined. 

7198 The delete statement shall remove an individual array element. Thus, the following code deletes 

7199 an entire array: 

7200 for (index in array) 

7201 delete array [index] 

7202 The next statement shall cause all further processing of the current input record to be 

7203 abandoned. The behavior is undefined if a next statement appears or is invoked in a BEGIN or 

7204 END action. 

7205 The exit statement shall invoke all END actions in the order in which they occur in the program 

7206 source and then terminate the program without reading further input. An exit statement inside 

7207 an END action shall terminate the program without further execution of END actions. If an 

7208 expression is specified in an exit statement, its numeric value shall be the exit status of awk, 

7209 unless subsequent errors are encountered or a subsequent exit statement with an expression is 

7210 executed. 
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7211 Output Statements 

7212 Both print and printf statements shall write to standard output by default. The output shall be 

7213 written to the location specified by output redirection if one is supplied, as follows: 


7214 > expression 

7215 >> expression 

7216 I expression 


7217 In all cases, the expression shall be evaluated to produce a string that is used as a path name into I 

7218 which to write (for ' >' or ">>") or as a command to be executed (for ' | Using the first two I 

7219 forms, if the file of that name is not currently open, it shall be opened, creating it if necessary and 

7220 using the first form, truncating the file. The output then shall be appended to the file. As long as 

7221 the file remains open, subsequent calls in which expression evaluates to the same string value 

7222 shall simply append output to the file. The file remains open until the close function (see 

7223 Input/Output and General Functions on page 202) is called with an expression that evaluates to 

7224 the same string value. 

7225 The third form shall write output onto a stream piped to the input of a command. The stream 

7226 shall be created if no stream is currently open with the value of expression as its command name. 

7227 The stream created shall be equivalent to one created by a call to the popen () function defined in 

7228 the System Interfaces volume of IEEE Std. 1003.1-200x with the value of expression as the 

7229 command argument and a value of iv as the mode argument. As long as the stream remains open, 

7230 subsequent calls in which expression evaluates to the same string value shall write output to the 

7231 existing stream. The stream shall remain open until the close function (see Input/Output and 

7232 General Functions on page 202) is called with an expression that evaluates to the same string 

7233 value. At that time, the stream shall be closed as if by a call to the pclose( ) function defined in 

7234 the System Interfaces volume of IEEE Std. 1003.1-200x. 

7235 As described in detail by the grammar in Grammar on page 204, these output statements shall 

7236 take a comma-separated list of expressions referred to in the grammar by the non-terminal 

7237 symbols expr list, print_expr_list, or print_expr_list_opt. This list is referred to here as the 

7238 expression list, and each member is referred to as an expression argument. 

7239 The print statement shall write the value of each expression argument onto the indicated output 

7240 stream separated by the current output field separator (see variable OFS above), and terminated 

7241 by the output record separator (see variable ORS above). All expression arguments shall be 

7242 taken as strings, being converted if necessary; this conversion shall be as described in 

7243 Expressions in awk on page 190, with the exception that the printf format in OFMT shall be 

7244 used instead of the value in CONVFMT. An empty expression list shall stand for the whole 

7245 input record ($0). 


7246 The printf statement shall produce output based on a notation similar to the File Format 

7247 Notation used to describe file formats in this volume of IEEE Std. 1003.1-200x (see the System I 

7248 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation). Output I 

7249 shall be produced as specified with the first expression argument as the string format and I 

7250 subsequent expression arguments as the strings argl to argn, inclusive, with the following 

7251 exceptions: 


7252 

7253 

7254 

7255 


1. The format shall be an actual character string rather than a graphical representation. 
Therefore, it cannot contain empty character positions. The <space> character in the format 
string, in any context other than a flag of a conversion specification, shall be treated as an 
ordinary character that is copied to the output. 


7256 2. If the character set contains a ' A' character and that character appears in the format string, 

7257 it shall be treated as an ordinary character that is copied to the output. 
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7258 3. The escape sequences beginning with a backslash character shall be treated as sequences of 

7259 ordinary characters that are copied to the output. Note that these same sequences shall be 

7260 interpreted lexically by awk when they appear in literal strings, but they shall not be 

7261 treated specially by the printf statement. 

7262 4. A field width or precision can be specified as the ' *' character instead of a digit string. In 

7263 this case the next argument from the expression list shall be fetched and its numeric value 

7264 taken as the field width or precision. 

7265 5. The implementation shall not precede or follow output from the d or u conversion 

7266 specifications with <blank> characters not specified by the format string. 

7267 6. The implementation shall not precede output from the o conversion specification with 

7268 leading zeros not specified by the format string. 

7269 7. For the c conversion specification: if the argument has a numeric value, the character 

7270 whose encoding is that value shall be output. If the value is zero or is not the encoding of 

7271 any character in the character set, the behavior is undefined. If the argument does not have 

7272 a numeric value, the first character of the string value shall be output; if the string does not 

7273 contain any characters, the behavior is undefined. 

7274 8. For each conversion specification that consumes an argument, the next expression 

7275 argument shall be evaluated. With the exception of the c conversion, the value shall be 

7276 converted (according to the rules specified in Expressions in awk on page 190) to the 

7277 appropriate type for the conversion specification. 

7278 9. If there are insufficient expression arguments to satisfy all the conversion specifications in 

7279 the format string, the behavior is undefined. 

7280 10. If any character sequence in the format string begins with a ' %' character, but does not 

7281 form a valid conversion specification, the behavior is unspecified. 

7282 Both print and printf can output at least |LINE_MAX} bytes. 

7283 Functions 

7284 The azvk language has a variety of built-in functions: arithmetic, string, input/output, and 

7285 general. 

7286 Arithmetic Functions 

7287 The arithmetic functions, except for int, shall be based on the ISO C standard. The behavior is 

7288 undefined in cases where the ISO C standard specifies that an error be returned or that the 

7289 behavior is undefined. Although the grammar (see Grammar on page 204) permits built-in 

7290 functions to appear with no arguments or parentheses, unless the argument or parentheses are 

7291 indicated as optional in the following list (by displaying them within the " [ ] " brackets), such 

7292 use is undefined. 

7293 atan2(y,x) Return arctangent of ij/x in radians in the range -|tt[ to {. 

7294 cos(x) Return cosine of x, where x is in radians. 

7295 sin(x) Return sine of x, where x is in radians. 

7296 exp(x) Return the exponential function of x. 

7297 log(x) Return the natural logarithm of x. 

7298 sqrt(x) Return the square root of x. 
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7299 

7300 

7301 

7302 


int(x) Truncate its argument to an integer. It shall be truncated toward 0 when x>0. 

rand( ) Return a random number n, such that 0</i<1. 

srand ([expr]) Set the seed value for rand to expr or use the time of day if expr is omitted. The 
previous seed value shall be returned. 


7303 String Functions 


7304 The string functions in the following list shall be supported. Although the grammar (see 

7305 Grammar on page 204) permits built-in functions to appear with no arguments or parentheses, 

7306 unless the argument or parentheses are indicated as optional in the following list (by displaying 

7307 them within the " [ ] " brackets), such use is undefined. 


7308 

7309 

7310 

7311 


gsub(ere, repl[, in]) 

Behave like sub (see below), except that it shall replace all occurrences of the 
regular expression (like the ed utility global substitute) in $0 or in the in argument, 
when specified. 


7312 index(s, t) Return the position, in characters, numbering from 1, in string s where string t first 

7313 occurs, or zero if it does not occur at all. 


7314 

7315 MAN 

7316 

7317 

7318 


length[([s])] Return the length, in characters, of its argument taken as a string, or of the whole 
record, $0, if there is no argument. The use of no argument and no parentheses 
with length is obsolescent in the IEEE Std. 1003.1-200x; to be fully portable I 
POSIX-conforming applications shall use length($0) for the length of the whole I 
record. 


7319 

7320 

7321 

7322 

7323 


match (s, ere) Return the position, in characters, numbering from 1, in string s where the 
extended regular expression ere occurs, or zero if it does not occur at all. RSTART 
shall be set to the starting position (which is the same as the returned value), zero 
if no match is found; RLENGTH shall be set to the length of the matched string, -1 
if no match is found. 


7324 

7325 

7326 

7327 

7328 

7329 

7330 


split(s, a[,fs ]) 

Split the string s into array elements a[ 1], a[ 2], ...,a[n], and return n. All elements 
of the array shall be deleted before the split is performed. The separation shall be 
done with the ERE/s or with the field separator FS if/s is not given. Each array 
element shall have a string value when created and, if appropriate, the array 
element shall be considered a numeric string (see Expressions in awk on page 
190). The effect of a null string as the value of/s is unspecified. 


7331 

7332 

7333 


sprintf (fmt, expr, expr,...) 

Format the expressions according to the printf format given by fmt and return the 
resulting string. 


7334 

7335 

7336 

7337 

7338 

7339 

7340 

7341 

7342 

7343 

7344 


sub (ere, repl[, in ]) 

Substitute the string repl in place of the first instance of the extended regular 
expression ERE in string in and return the number of substitutions. An ampersand 
(' &') appearing in the string repl shall be replaced by the string from in that 
matches the ERE. An ampersand preceded with a backslash ('V) shall be 
interpreted as the literal ampersand character. Any other occurrence of a backslash 
(for example, preceding any other character) shall be treated as a literal backslash 
character. Note that if repl is a string literal (the lexical token STRING; see 
Grammar on page 204), the handling of the ampersand character occurs after any 
lexical processing, including any lexical backslash escape sequence processing. If 
in is specified and it is not an lvalue (see Expressions in awk on page 190), the 
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7345 behavior is undefined. If in is omitted, awk shall use the current record ($0) in its I 

7346 place. I 


7347 

7348 

7349 

7350 


substr(s, ml, n ]) 

Return the at most n -character substring of s that begins at position m, numbering 
from 1. If n is missing, or if n specifies more characters than are left in the string, I 
the length of the substring shall be limited by the length of the string s. I 


7351 

7352 

7353 

7354 


tolower(s) Return a string based on the string s. Each character in s that is an uppercase letter 
specified to have a tolower mapping by the LC_CTYPE category of the current 
locale shall be replaced in the returned string by the lowercase letter specified by 
the mapping. Other characters in s shall be unchanged in the returned string. 


7355 

7356 

7357 

7358 


toupper(s) Return a string based on the string s. Each character in s that is a lowercase letter 
specified to have a toupper mapping by the LCjCTYPE category of the current 
locale is replaced in the returned string by the uppercase letter specified by the 
mapping. Other characters in s are unchanged in the returned string. 


7359 All of the preceding functions that take ERE as a parameter expect a pattern or a string valued 

7360 expression that is a regular expression as defined in Regular Expressions on page 195. 


7361 Input/Output and General Functions 


7362 The input/output and general functions are: 


7363 

7364 

7365 

7366 

7367 


close (expression) 

Close the file or pipe opened by a print or printf statement or a call to getline with 
the same string-valued expression. The limit on the number of open expression 
arguments is implementation-dependent. If the close was successful, the function 
shall return zero; otherwise, it shall return non-zero. 


7368 

7369 

7370 

7371 

7372 

7373 

7374 

7375 

7376 

7377 

7378 

7379 


expression I getline [var] 

Read a record of input from a stream piped from the output of a command. The 
stream shall be created if no stream is currently open with the value of expression as 
its command name. The stream created shall be equivalent to one created by a call 
to the popen () function with the value of expression as the command argument and a 
value of r as the mode argument. As long as the stream remains open, subsequent 
calls in which expression evaluates to the same string value shall read subsequent 
records from the stream. The stream shall remain open until the close function is I 
called with an expression that evaluates to the same string value. At that time, the 
stream shall be closed as if by a call to the pclose () function. If var is missing, $0 and 
NF shall be set; otherwise, var shall be set and, if appropriate, it shall be considered I 
a numeric string (see Expressions in awk on page 190). I 


7380 

7381 

7382 

7383 

7384 

7385 


The getline operator can form ambiguous constructs when there are 
unparenthesized operators (including concatenate) to the left of the ' | ' (to the 
beginning of the expression containing getline). In the context of the ' 
operator, ' | ' shall behave as if it had a lower precedence than ' $'. The result of 
evaluating other operators is unspecified, and portable applications shall I 
parenthesize properly all such usages. I 


7386 getline Set $0 to the next input record from the current input file. This form of getline shall 

7387 set the NF, NR, and FNR variables. 


7388 getline var Set variable var to the next input record from the current input file and, if I 

7389 appropriate, var shall be considered a numeric string (see Expressions in awk on I 

7390 page 190). This form of getline shall set the FNR and NR variables. I 
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getline [var] < expression 

Read the next record of input from a named file. The expression shall be evaluated I 
to produce a string that is used as a path name. If the file of that name is not I 
currently open, it shall be opened. As long as the stream remains open, subsequent 
calls in which expression evaluates to the same string value shall read subsequent 
records from the file. The file shall remain open until the close function is called 
with an expression that evaluates to the same string value. If var is missing, $0 and 
NF shall be set; otherwise, var shall be set and, if appropriate, it shall be considered I 
a numeric string (see Expressions in awk on page 190). I 

The getline operator can form ambiguous constructs when there are 
unparenthesized binary operators (including concatenate) to the right of the ' <' 

(up to the end of the expression containing the getline). The result of evaluating 
such a construct is unspecified, and portable applications shall parenthesize I 
properly all such usages. I 

system (express ion) 

Execute the command given by expression in a manner equivalent to the system () 
function defined in the System Interfaces volume of IEEE Std. 1003.1-200x and 
return the exit status of the command. 

All forms of getline shall return 1 for successful input, zero for end-of-file, and -1 for an error. 

Where strings are used as the name of a file or pipeline, the application shall ensure that the I 
strings are textually identical. The terminology "same string value" implies that "equivalent I 
strings", even those that differ only by <space> characters, represent different files. I 


7413 User-Defined Functions 

7414 The awk language also provides user-defined functions. Such functions can be defined as: 

7415 function name ([parameter, ...]) { statements } 

7416 A function can be referred to anywhere in an awk program; in particular, its use can precede its 

7417 definition. The scope of a function is global. 

7418 Function parameters, if present, can be either scalars or arrays; the behavior is undefined if an I 

7419 array name is passed as a parameter that the function uses as a scalar, or if a scalar expression is I 

7420 passed as a parameter that the function uses as an array. Function parameters shall be passed by I 

7421 value if scalar and by reference if array name. I 

7422 The number of parameters in the function definition need not match the number of parameters 

7423 in the function call. Excess formal parameters can be used as local variables. If fewer arguments 

7424 are supplied in a function call than are in the function definition, the extra parameters that are I 

7425 used in the function body as scalars shall evaluate to the uninitialized value until they are I 

7426 otherwise initialized, and the extra parameters that are used in the function body as arrays shall I 

7427 be treated as uninitialized arrays where each element evaluates to the uninitialized value until I 

7428 otherwise initialized. I 

7429 When invoking a function, no white space can be placed between the function name and the 

7430 opening parenthesis. Function calls can be nested and recursive calls can be made upon 

7431 functions. Upon return from any nested or recursive function call, the values of all of the calling 

7432 function's parameters shall be unchanged, except for array parameters passed by reference. The 

7433 return statement can be used to return a value. If a return statement appears outside of a 

7434 function definition, the behavior is undefined. 

7435 In the function definition, <newline> characters shall be optional before the opening brace and 

7436 after the closing brace. Function definitions can appear anywhere in the program where a 
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pattern-action pair is allowed. 

Grammar 

The grammar in this section and the lexical conventions in the following section shall together 
describe the syntax for azvk programs. The general conventions for this style of grammar are 


7441 

7442 

7443 

described in Section 1.10 on page 24. A valid program can be represented 
symbol program in the grammar. This formal syntax shall take precedence 
text syntax description. 

7444 

%token NAME 

NUMBER 

STRING ERE 



7445 

%token FUNC_ 

NAME 

/* Name followed by '(' without white 

7446 

/* Keywords 

*/ 




7447 

%token 

Begin 

End 



7448 

/* 

' BEGIN' 

' END' 


*/ 

7449 

%token 

Break 

Continue Delete Do 

Else 


7450 

/* 

'break' 

'continue' 'delete' 'do' 

'else' 

*/ 

7451 

%token 

Exit 

For Function If In 



7452 

/* 

' exit ' 

'for' 'function' 'if' 'in' 


*/ 

7453 

%token 

Next 

Print Printf Return 

While 


7454 

/* 

' next ' 

'print' 'printf' 'return' 

' while' 

*/ 

7455 

/* Reserved 

function names */ 



7456 

%token BUILTIN_FUNC 

_NAME 



7457 


/* One 

token for the following: 



7458 


* atan2 cos sin exp log sqrt int 

rand srand 

7459 


* gsub 

index length match split 

sprintf 

sub 

7460 


* substr tolower toupper close system 


7461 


*/ 





%token GETLINE 

/* Syntactically different from other built-ins. */ 

/* Two-character tokens. */ 

%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN 
/* '+=' '*=' '/ = ' '% = ' '" = ' */ 

%token OR AND NO_MATCH EQ LE GE NE INCR DECR APPEND 

/* 'II' '&&' ' \ ~' '==' '<=' '>=' '!=' '+ + ' ' '»' */ 

/* One-character tokens. */ 

%token '{' '}' '(' ')' ' [' ']' ';' NEWLINE 

%token '+' '*' '%' '"' ' ! ' '>' '<' ' \' ' ?' ' ~' '$' '=' 

%start program 


program 


: item_list 

I actionless_item_list 


item_list 


: newline_opt 

I actionless_item_list item terminator 
I item_list item terminator 
I item_list action terminator 
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7482 actionless_item_list : item_list pattern terminator 

7483 I actionless_item_list pattern terminator 

7484 ; 


7485 item 

7486 

7487 

7488 

7489 

7490 


: pattern action 

I Function NAME '(' param_list_opt ')' 

newline_opt action 

I Function FUNC_NAME '(' param_list_opt ')' 
newline_opt action 


7491 param_list_opt 

7492 

7493 

7494 param_list 

7495 

7496 

7497 pattern 

7498 

7499 

7500 

7501 


: /* empty */ 

| param_list 

r 

: NAME 

I param_list ', ' NAME 

f 

: Begin 
I End 
| expr 

I expr ',' newline_opt expr 


7502 action 

7503 

7504 

7505 


: ' {' newline_opt ' }' 
| '{' newline_opt terminated_statement_list '}' 
| '{' newline_opt unterminated_statement_list '}' 


7506 

7507 

7508 

7509 

7510 


terminator 


: terminator ' ; ' 

| terminator NEWLINE 

I ' ; ' 

| NEWLINE 


7511 terminated_statement_list : terminated_statement 

7512 I terminated_statement_list terminated_statement 

7513 ; 


7514 unterminated_statement_list : unterminated_statement 

7515 I terminated_statement_list unterminated_statement 

7516 ; 


7517 

7518 

7519 

7520 

7521 

7522 

7523 

7524 

7525 

7526 

7527 

7528 

7529 


terminated_statement : action newline_opt 

| If ' (' expr ')' newline_opt terminated_statement 
| If '(' expr ')' newline_opt terminated_statement 
Else newline_opt terminated_statement 
| While ' (' expr ')' newline_opt terminated_statement 
| For '(' simple_statement_opt 

expr_opt ';' simple_statement_opt ')' newline_opt 
terminated_statement 
| For ' (' NAME In NAME ')' newline_opt 
terminated_statement 
| ';' newline_opt 

| terminatable_statement NEWLINE newline_opt 
| terminatable_statement ';' newline_opt 
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7530 


7531 

7532 

7533 

7534 

7535 

7536 

7537 

7538 

7539 

7540 

7541 


unterminated_statement : terminatable_statement 

| If ' (' expr ')' newline_opt unterminated_statement 
| If '(' expr ')' newline_opt terminated_statement 
Else newline_opt unterminated_statement 
| While ' (' expr ')' newline_opt unterminated_statement 
| For '(' simple_statement_opt 

expr_opt ';' simple_statement_opt ')' newline_opt 
unterminated_statement 
| For ' (' NAME In NAME ')' newline_opt 
unterminated_statement 


7542 

7543 

7544 

7545 

7546 

7547 

7548 

7549 


terminatable_statement : simple_statement 
| Break 
I Continue 
I Next 

I Exit expr_opt 
I Return expr_opt 

| Do newline_opt terminated_statement While '(' expr ')' 


7550 simple_statement_opt : /* empty */ 


7551 I 

7552 ; 

7553 simple_statement : 

7554 | 

7555 I 

7556 ; 


simple_statement 

Delete NAME '[' expr_list ']' 
expr 

print_statement 


7557 print_statement : simple_print_statement 

7558 I simple_print_statement output_redirection 

7559 ; 


7560 

7561 

7562 

7563 

7564 


simple_print_statement : Print print_expr_list_opt 
| Print '(' multiple_expr_list ')' 
| Printf print_expr_list 
| Printf '(' multiple_expr_list ')' 


7565 

7566 

7567 

7568 


output_redirection : '>' expr 

| APPEND expr 
| '|' expr 


7569 

7570 

7571 


e xp r_lis t_opt 


: /* empty */ 
I expr_list 


7572 expr_list 

7573 

7574 


: expr 

I multiple_expr_list 


7575 

7576 


multiple_expr_list 


: expr ',' newline_opt expr 
multiple_expr_list ',' newline_opt expr 
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7577 






7578 

expr_opt 


/* empty */ 



7579 



expr 



7580 






7581 

expr 


unary_expr 



7582 



non_unary_expr 



7583 






7584 

unary_expr 


'+' expr 



7585 



' —' expr 



7586 



unary_expr ' "' 


expr 

7587 



unary_expr '*' 


expr 

7588 



unary_expr '/' 


expr 

7589 



unary_expr '%' 


expr 

7590 



unary_expr '+' 


expr 

7591 



unary_expr '—' 


expr 

7592 



unary_expr 


non_unary_expr 

7593 



unary_expr '<' 


expr 

7594 



unary_expr LE 


expr 

7595 



unary_expr NE 


expr 

7596 



unary_expr EQ 


expr 

7597 



unary_expr ' >' 


expr 

7598 



unary_expr GE 


expr 

7599 



unary_expr 


expr 

7600 



unary_expr NO_MATCH expr 

7601 



unary_expr In NAME 


7602 



unary_expr AND 

newline_opt expr 

7603 



unary_expr OR 

newline_opt expr 

7604 



unary_expr '?' 

expr ':' expr 

7605 



unary_input_function 

7606 






7607 

non_unary_expr 


' (' expr ')' 



7608 



' ! ' expr 



7609 



non_unary_expr 

i ^ r 

expr 

7610 



non_unary_expr 

f * ' 

expr 

7611 



non_unary_expr 

' /' 

expr 

7612 



non_unary_expr 

r o, r 

o 

expr 

7613 



non_unary_expr 

' +' 

expr 

7614 



non_unary_expr 

i _ i 

expr 

7615 



non_unary_expr 


non_unary_ 

7616 



non_unary_expr 

• <’ 

expr 

7617 



non_unary_expr 

LE 

expr 

7618 



non_unary_expr 

NE 

expr 

7619 



non_unary_expr 

EQ 

expr 

7620 



non_unary_expr 

' >' 

expr 

7621 



non_unary_expr 

GE 

expr 

7622 



non_unary_expr 

r ~ r 

expr 

7623 



non_unary_expr 

NO_ 

MATCH expr 

7624 



non_unary_expr 

In 

NAME 

7625 



'(' multiple_expr_ 

list ')' In NAME 

7626 



non_unary_expr 

AND 

newline_opt exp 


Commands and Utilities, Issue 6 


207 





awk 


Utilities 


7627 

7628 

7629 

7630 

7631 

7632 

7633 

7634 

7635 

7636 

7637 

7638 

7639 

7640 

7641 

7642 

7643 

7644 

7645 

7646 

7647 

7648 

7649 


I non_unary_expr OR newline_opt expr 
I non_unary_expr '?' expr 'expr 
| NUMBER 
| STRING 
I lvalue 
| ERE 

I lvalue INCR 
I lvalue DECR 
| INCR lvalue 
| DECR lvalue 
I lvalue POW_ASSIGN expr 
I lvalue MOD_ASSIGN expr 
I lvalue MUL_ASSIGN expr 
I lvalue DIV_ASSIGN expr 
I lvalue ADD_ASSIGN expr 
I lvalue SUB_ASSIGN expr 
I lvalue '=' expr 

| FUNC_NAME '(' expr_list_opt ')' 

/* no white space allowed before ' (' */ 
| BUILTIN_FUNC_NAME '(' expr_list_opt ')' 

| B UIL TI N_F UN C_N AME 
I non_unary_input_function 


7650 print_expr_list_opt : /* empty */ 

7651 I print_expr_list 

7652 ; 


7653 print_expr_list : print_expr 

7654 | print_expr_list ' , ' newline_opt print_expr 

7655 ; 


7656 print_expr : unary_print_expr 

7657 | non_unary_print_expr 

7658 ; 


7659 

7660 

7661 

7662 

7663 

7664 

7665 

7666 

7667 

7668 

7669 

7670 

7671 

7672 

7673 

7674 


unary_print_expr : '+' print_expr 

| '—' print_expr 

| unary_print_expr '"' print_expr 

| unary_print_expr print_expr 

| unary_print_expr '/' print_expr 

| unary_print_expr '%' print_expr 

| unary_print_expr '+' print_expr 

| unary_print_expr ' print_expr 
| unary_print_expr non_unary_print_expr 

| unary_print_expr print_expr 

| unary_print_expr NO_MATCH print_expr 

| unary_print_expr In NAME 

| unary_print_expr AND newline_opt print_expr 

| unary_print_expr OR newline_opt print_expr 

| unary_print_expr '?' print_expr 'print_expr 


7675 non_unary_print_expr : ' (' expr ')' 

7676 I ' \ ' print_expr 
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7677 

7678 

7679 

7680 

7681 

7682 

7683 

7684 

7685 

7686 

7687 

7688 

7689 

7690 

7691 

7692 

7693 

7694 

7695 

7696 

7697 

7698 

7699 

7700 

7701 

7702 

7703 

7704 

7705 

7706 

7707 

7708 

7709 

7710 


I non_unary_print_expr 'print_expr 
I non_unary_print_expr print_expr 

I non_unary_print_expr '/' print_expr 

I non_unary_print_expr '%' print_expr 

I non_unary_print_expr '+' print_expr 

I non_unary_print_expr ' print_expr 
I non_unary_print_expr non_unary_print_expr 

I non_unary_print_expr print_expr 

I non_unary_print_expr NO_MATCH print_expr 

I non_unary_print_expr In NAME 
| '(' multiple_expr_list ')' In NAME 

I non_unary_print_expr AND newline_opt print_expr 
I non_unary_print_expr OR newline_opt print_expr 
I non_unary_print_expr '?' print_expr 'print_expr 
| NUMBER 
| STRING 
I lvalue 
| ERE 

I lvalue INCR 
I lvalue DECR 
| INCR lvalue 
| DECR lvalue 

I lvalue POW_ASSIGN print_expr 
I lvalue MOD_ASSIGN print_expr 
I lvalue MUL_ASSIGN print_expr 
I lvalue DIV_ASSIGN print_expr 
I lvalue ADD_ASSIGN print_expr 
I lvalue SUB_ASSIGN print_expr 
I lvalue '=' print_expr 
| FUNC_NAME '(' expr_list_opt ')' 

/* no white space allowed before ' (' */ 

| BUILTIN_FUNC_NAME '(' expr_list_opt ')' 

| B UIL TI N_F UN C_N AME 


7711 lvalue : NAME 

7712 | NAME '[' expr_list ']' 

7713 I '$' expr 

7714 ; 


7715 non_unary_input_function : simple_get 

7716 I simple_get ' <’ expr 

7717 | non_unary_expr ' \ ' simple_get 

7718 ; 


7719 unary_input_function : unary_expr '|' simple_get 

7720 ; 


7721 

simple_get 

: GETLINE 

7722 


| GETLINE lvalue 

7723 


r 

7724 

newline_opt 

: /* empty */ 

7725 


| newline_opt NEWLINE 

7726 


r 
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7727 This grammar has several ambiguities that shall be resolved as follows: 

7728 • Operator precedence and associativity shall be as described in Table 4-1 on page 190. 

7729 • In case of ambiguity, an else shall be associated with the most immediately preceding if that 

7730 would satisfy the grammar. 

7731 • In some contexts, a slash (' /') that is used to surround an ERE could also be the division 

7732 operator. This shall be resolved in such a way that wherever the division operator could 

7733 appear, a slash is assumed to be the division operator. (There is no unary division operator.) 

7734 One convention that might not be obvious from the formal grammar is where <newline> 

7735 characters are acceptable. There are several obvious placements such as terminating a statement, 

7736 and a backslash can be used to escape <newline> characters between any lexical tokens. In 

7737 addition, <newline> characters without backslashes can follow a comma, an open brace, logical 

7738 AND operator ("&&"), logical OR operator (" | | "), the do keyword, the else keyword, and the 

7739 closing parenthesis of an if, for, or while statement. For example: 

7740 { print $1, 

7741 $2 } 


7742 Lexical Conventions 

7743 The lexical conventions for awk programs, with respect to the preceding grammar, shall be as 

7744 follows: 


7745 

7746 


1. Except as noted, awk shall recognize the longest possible token or delimiter beginning at a 
given point. 


7747 

7748 

7749 


2. A comment shall consist of any characters beginning with the number sign character and 
terminated by, but excluding the next occurrence of, a <newline> character. Comments 
shall have no effect, except to delimit lexical tokens. 


7750 

7751 

7752 

7753 

7754 

7755 

7756 

7757 

7758 

7759 

7760 

7761 


3. The <newline> character shall be recognized as the token NEWLINE. 

4. A backslash character immediately followed by a <newline> character shall have no effect. 

5. The token STRING shall represent a string constant. A string constant shall begin with the 
character ' "'. Within a string constant, a backslash character shall be considered to begin I 
an escape sequence as specified in the table in the System Interface Definitions volume of I 
IEEEStd. 1003.1-200x, Chapter 5, File Format Notation (' W, ' \a', ' \b', ' \f', ' \n', I 
' \r', ' \t', ' \v'). In addition, the escape sequences in Table 4-2 on page 195 shall be 
recognized. A <newline> character shall not occur within a string constant. A string 
constant shall be terminated by the first unescaped occurrence of the character ' "' after 
the one that begins the string constant. The value of the string shall be the sequence of all 
unescaped characters and values of escape sequences between, but not including, the two 
delimiting ' " ' characters. 


7762 

7763 

7764 

7765 

7766 

7767 

7768 

7769 

7770 

7771 


6. The token ERE represents an extended regular expression constant. An ERE constant shall 
begin with the slash character. Within an ERE constant, a backslash character shall be 
considered to begin an escape sequence as specified in the table in the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation. In addition, 
the escape sequences in Table 4-2 on page 195 shall be recognized. The application shall 
ensure that a <newline> character does not occur within an ERE constant. An ERE constant 
shall be terminated by the first unescaped occurrence of the slash character after the one 
that begins the ERE constant. The extended regular expression represented by the ERE 
constant shall be the sequence of all unescaped characters and values of escape sequences 
between, but not including, the two delimiting slash characters. 
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7. A <blank> character shall have no effect, except to delimit lexical tokens or within 
STRING or ERE tokens. 

8. The token NUMBER shall represent a numeric constant. Its form and numeric value shall 
be equivalent to either of the tokens floating-constant or integer-constant as specified by 
the ISO C standard, with the following exceptions: 

a. An integer constant cannot begin with Ox or include the hexadecimal digits ' a', ' b', 
' c', ' d', ' e', ' f ', ' A', ' B', ' C', ' D', ' E',or ' F'. 


b. The value of an integer constant beginning with 0 shall be taken in decimal rather 
than octal. 

c. An integer constant cannot include a suffix (' u' , ' U' , ' 1', or ' L' ). 

d. A floating constant cannot include a suffix (' f', ' F', ' 1', or ' L '). 

If the value is too large or too small to be representable, the behavior is undefined. 

9. A sequence of underscores, digits, and alphabetics from the portable character set (see the I 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable I 
Character Set), beginning with an underscore or alphabetic, shall be considered a word. I 

10. The following words are keywords that shall be recognized as individual tokens; the name 
of the token is the same as the keyword: 


7789 

BEGIN 

delete 

END 

function 

in 

printf 

7790 

break 

do 

exit 

getline 

next 

return 

7791 

continue 

else 

for 

if 

print 

while 

7792 

7793 

11. The following words are names of built-in functions and shall be 
BUILTIN_FUNC_NAME: 

recognized 

7794 

atan2 

gsub 

log 

split 

sub 

toupper 

7795 

close 

index 

match 

sprintf 

substr 


7796 

cos 

int 

rand 

sqrt 

system 


7797 

exp 

length 

sin 

srand 

tolower 



7798 The above-listed keywords and names of built-in functions are considered reserved words. 

7799 1 2. The token NAME shall consist of a word that is not a keyword or a name of a built-in 

7800 function and is not followed immediately (without any delimiters) by the ' (' character. 

7801 13. The token FUNC_NAME shall consist of a word that is not a keyword or a name of a 

7802 built-in function, followed immediately (without any delimiters) by the ' (' character. The 

7803 ' (' character shall not be included as part of the token. 

7804 14. The following two-character sequences shall be recognized as the named tokens: 


7805 

Token Name 

Sequence 

Token Name 

Sequence 

7806 

ADD_ASSIGN 

+= 

NO MATCH 

! ~ 

7807 

SUB_ASSIGN 

-= 

EQ 

= = 

7808 

MUL_ASSIGN 

~k = 

LE 

< = 

7809 

DIV_ASSIGN 

/ = 

GE 

> = 

7810 

MOD_ASSIGN 

"6 = 

NE 

1 = 

7811 

POW_ASSIGN 

a = 

INCR 

+ + 

7812 

OR 

1 1 

DECR 

— 

7813 

AND 

&& 

APPEND 

>> 
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7814 15. The following single characters shall be recognized as tokens whose names are the 

7815 character: 

7816 <newline> {} () [],;+ — *%~!><|?:~$ = 

7817 There is a lexical ambiguity between the token ERE and the tokens ' /' and DIV_ASSIGN. 

7818 When an input sequence begins with a slash character in any syntactic context where the token 

7819 ' /' or DIV_ASSIGN could appear as the next token in a valid program, the longer of those two 

7820 tokens that can be recognized shall be recognized. In any other syntactic context where the token 

7821 ERE could appear as the next token in a valid program, the token ERE shall be recognized. 

7822 EXIT STATUS 

7823 The following exit values shall be returned: 

7824 0 All input files were processed successfully. 

7825 >0 An error occurred. 

7826 The exit status can be altered within the program by using an exit expression. 

7827 CONSEQUENCES OF ERRORS 

7828 If any file operand is specified and the named file cannot be accessed, azvk shall write a 

7829 diagnostic message to standard error and terminate without any further action. 

7830 If the program specified by either the program operand or a progfile operand is not a valid awk 

7831 program (as specified in the EXTENDED DESCRIPTION section), the behavior is undefined. 

7832 APPLICATION USAGE 

7833 The index, length, match, and substr functions should not be confused with similar functions in 

7834 the ISO C standard; the awk versions deal with characters, while the ISO C standard deals with 

7835 bytes. 

7836 Because the concatenation operation is represented by adjacent expressions rather than an 

7837 explicit operator, it is often necessary to use parentheses to enforce the proper evaluation 

7838 precedence. 

7839 EXAMPLES 

7840 The azvk program specified in the command line is most easily specified within single-quotes (for 

7841 example, 'program') for applications using sh, because azvk programs commonly contain 

7842 characters that are special to the shell, including double-quotes. In the cases where an azvk 

7843 program contains single-quote characters, it is usually easiest to specify most of the program as 

7844 strings within single-quotes concatenated by the shell with quoted single-quote characters. For 

7845 example: 

7846 awk ' /'\'' / { print "quote:", $0 }' 

7847 prints all lines from the standard input containing a single-quote character, prefixed with quote:. 

7848 The following are examples of simple azvk programs: 

7849 1. Write to the standard output all input lines for which field 3 is greater than 5: 

7850 $3 > 5 

7851 2. Write every tenth line: 

7852 (NR % 10) == 0 

7853 3. Write any line with a substring matching the regular expression: 

7854 / (G | D) (2 [ 0—9 ] [[: alpha :]]*)/ 
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7855 

7856 

7857 

7858 

7859 

7860 

7861 

7862 

7863 

7864 

7865 

7866 

7867 

7868 

7869 

7870 

7871 

7872 

7873 

7874 

7875 

7876 

7877 

7878 

7879 

7880 

7881 

7882 

7883 

7884 

7885 

7886 

7887 

7888 

7889 

7890 

7891 

7892 

7893 


4. Print any line with a substring containing a ' G' or ' D', followed by a sequence of digits 
and characters. This example uses character classes digit and alpha to match language- 
independent digit and alphabetic characters respectively: 

/(G|D) ([[:digit: ] [:alpha:]]*) / 

5. Write any line in which the second field matches the regular expression and the fourth 
field does not: 

$2 ~ /xyz/ && $4 !~ /xyz/ 

6. Write any line in which the second field contains a backslash: 

$2 " /\\/ 

7. Write any line in which the second field contains a backslash. Note that backslash escapes 
are interpreted twice, once in lexical processing of the string and once in processing the 
regular expression: 

$2 ~ "\\\\" 

8. Write the second to the last and the last field in each line. Separate the fields by a colon: 

{OFS=":";print $(NF-1), $NF} 

9. Write the line number and number of fields in each line. The three strings representing the 
line number, the colon, and the number of fields are concatenated and that string is written 
to standard output: 

{print NR NF} 

10. Write lines longer than 72 characters: 

length($0) >72 

11. Write first two fields in opposite order separated by the OFS: 

{ print $2, $1 } 

12. Same, with input fields separated by comma or <space> and <tab> characters, or both: 

BEGIN { FS = ", [ \t]* | [ \t]+" } 

{ print $2, $1 } 

13. Add up first column, print sum, and average: 

{s += $1 } 

END {print "sum is ", s, " average is", s/NR} 

14. Write fields in reverse order, one per line (many lines out for each line in): 

{ for (i = NF; i > 0; —i) print $i } 

15. Write all lines between occurrences of the strings start and stop: 

/start/, /stop/ 

16. Write all lines whose first field is different from the previous one: 

$1 != prev { print; prev = $1 } 

17. Simulate echo: 

BEGIN { 

for (i = 1; i < ARGC; ++i) 

printf("%s%s", ARGV[i], i==ARGC-l?"\n":" ") 
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7894 

7895 

7896 

7897 

7898 

7899 

7900 


} 

18. Write the path prefixes contained in the PATH environment variable, one per line: 

BEGIN { 

n = split (ENVIRON["PATH"], path, 
for (i = 1; i <= n; ++i) 
print path[i] 

} 


7901 

7902 

7903 

7904 

7905 

7906 


19. If there is a file named input containing page headers of the form: 
Page # 

and a file named program that contains: 

/Page/ { $2 = n++; } 

{ print } 

then the command line: 


7907 


awk —f program n=5 input 


7908 

7909 RATIONALE 

7910 

7911 

7912 

7913 


prints the file input, filling in page numbers starting at 5. 


7914 

7915 

7916 

7917 

7918 

7919 

7920 

7921 

7922 

7923 

7924 

7925 

7926 

7927 

7928 

7929 

7930 

7931 

7932 

7933 

7934 

7935 

7936 

7937 


In sub and gsub, if repl is a string literal (the lexical token STRING), then two consecutive 
backslash characters should be used in the string to ensure a single backslash will precede the 
ampersand when the resultant string is passed to the function. (For example, to specify one 
literal ampersand in the replacement string, use gsub(ERE, " \ \ & ").) 

Historically the only special character in the repl argument of sub and gsub string functions was 
the ampersand (' &') character and preceding it with the backslash character was used to turn 
off its special meaning. 

The description in the ISO POSIX-2:1993 standard introduced behavior such that the backslash 
character was another special character and it was unspecified whether there were any other 
special characters. This description introduced several portability problems, some of which are 
described below, and so it has been replaced with the more historical description. Some of the 
problems include: 

• Historically, to create the replacement string, a script could use gsub(ERE, " \ \& "), but with 
the ISO POSIX-2:1993 standard wording, it was necessary to use gsub(ERE, "\\\\&"). 
Backslash characters are doubled here because all string literals are subject to lexical analysis, 
which would reduce each pair of backslash characters to a single backslash before being 
passed to gsub. 

• Since it was unspecified what the special characters were, for portable scripts to guarantee 
that characters are printed literally, each character had to be preceded with a backslash. (For 
example, a portable script had to use gsub (ERE, "\\h\\i") to produce a replacement string 
of "hi".) 

The description for comparisons in the ISO POSIX-2:1993 standard did not properly describe 
historical practice because of the way numeric strings are compared as numbers. The current 
rules cause the following code: 

if (0 == "000") 

print "strange, but true" 

else 

print "not true" 
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7938 to do a numeric comparison, causing the if to succeed. It should be intuitively obvious that this 

7939 is incorrect behavior, and indeed, no historical implementation of aivk actually behaves this way. 

7940 To fix this problem, the definition of numeric string was enhanced to include only those values 

7941 obtained from specific circumstances (mostly external sources) where it is not possible to 

7942 determine unambiguously whether the value is intended to be a string or a numeric. 

7943 Variables that are assigned to a numeric string shall also be treated as a numeric string. (For 

7944 example, the notion of a numeric string can be propagated across assignments.) In comparisons, 

7945 all variables having the uninitialized value are to be treated as a numeric operand evaluating to 

7946 the numeric value zero. 

7947 Uninitialized variables include all types of variables including scalars, array elements, and fields. 

7948 The definition of an uninitialized value is necessary to describe the value placed on uninitialized 

7949 variables and on fields that are valid (for example, <$NF) but have no characters in them and to 

7950 describe how these variables are to be used in comparisons. A valid field, such as $1, that has no 

7951 characters in it can be obtained by from an input line of "\t\t" when FS="\t". Historically, 

7952 the comparison ($1<10) was done numerically after evaluating $1 to the value zero. 

7953 The phrase "... also shall have the numeric value of the numeric string" was removed from 

7954 several sections of t ISO POSIX-2 standard because they specify an unnecessary implementation 

7955 detail. It is not necessary for IEEE Std. 1003.1-200x to specify that these objects be assigned two 

7956 different values. It is only necessary to specify that these objects may evaluate to two different 

7957 values depending on context. 

7958 The description of numeric string processing is based on the behavior of the atof( ) function in 

7959 the ISO C standard. While it is not a requirement for an implementation to use this function, 

7960 many historical implementations of aivk do. In the ISO C standard, floating point constants use a 

7961 period as a decimal point character for the language itself, independent of the current locale, but 

7962 the atof() function and the associated strtod() function use the decimal point character of the 

7963 current locale when converting strings to numeric values. Similarly in awk, floating point 

7964 constants in an awk script use a period independent of the locale, but input strings use the 

7965 decimal point character of the locale. 

7966 The ISO POSIX-2 standard description is based on the new awk, "nawk", (see the referenced The 

7967 AWK Programming Language), which introduced a number of new features to the historical aivk: 

7968 1. New keywords: delete, do, functin, return 

7969 2. New built-in functions: atan2, close, cos, gsub, match, rand, sin, srand, sub, system 

7970 3. New predefined variables: FNR, ARGC, ARGV, RSTART, RLENGTH, SUB SEP 

7971 4. New expression operators: ?,:, „' 

7972 5. The FS variable and the third argument to split, now treated as extended regular 

7973 expressions. 

7974 6. The operator precedence, changed to more closely match the C language. Two examples 

7975 of code that operate differently are: 

7976 while ( n /= 10 > 1) ... 

7977 if ( ! " wk" ~ /bwk/) ... 

7978 Several features have been added based on newer implementations of aivk: 

7979 • Multiple instances of -f progfile are permitted 

7980 • The new option -v assignment 
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7981 • The new predefined variable ENVIRON 

7982 • New built-in functions toupper, and tolower 

7983 • More formatting capabilities are added to printf to match the ISO C standard 

7984 The overall azvk syntax has always been based on the C language, with a few features from the 

7985 shell command language and other sources. Because of this, it is not completely compatible with 

7986 any other language, which has caused confusion for some users. It is not the intent of the 

7987 standard developers to address such issues. IEEE Std. 1003.1-200x has made a few relatively 

7988 minor changes toward making the language more compatible with the C language as specified 

7989 by the ISO C standard; most of these changes are based on similar changes in recent 

7990 implementations, as described above. There remain several C-language conventions that are not 

7991 in azvk. One of the notable ones is the comma operator, which is commonly used to specify 

7992 multiple expressions in the C language for statement. Also, there are various places where azvk is 

7993 more restrictive than the C language regarding the type of expression that can be used in a given 

7994 context. These limitations are due to the different features that the azvk language does provide. 

7995 Regular expressions in azvk have been extended somewhat from historical implementations to 

7996 make them a pure superset of extended regular expressions, as defined by IEEE Std. 1003.1-200x 

7997 (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.4, Extended 

7998 Regular Expressions). The main extensions are internationalization features and interval 

7999 expressions. Historical implementations of azvk have long supported backslash escape sequences 

8000 as an extension to extended regular expressions, and this extension has been retained despite 

8001 inconsistency with other utilities. The number of escape sequences recognized in both extended 

8002 regular expressions and strings has varied (generally increasing with time) among 

8003 implementations. The set specified by IEEE Std. 1003.1-200x includes most sequences known to 

8004 be supported by popular implementations and by the ISO C standard. One sequence that is not 

8005 supported is hexadecimal value escapes beginning with ' \x'. This would allow values 

8006 expressed in more than 9 bits to be used within azvk as in the ISO C standard. However, because 

8007 this syntax has a non-deterministic length, it does not permit the subsequent character to be a 

8008 hexadecimal digit. This limitation can be dealt with in the C language by the use of lexical string 

8009 concatenation. In the azvk language, concatenation could also be a solution for strings, but not for 

8010 extended regular expressions (either lexical ERE tokens or strings used dynamically as regular 

8011 expressions). Because of this limitation, the feature has not been added to IEEE Std. 1003.1-200x. 

8012 When a string variable is used in a context where an extended regular expression normally 

8013 appears (where the lexical token ERE is used in the grammar) the string does not contain the 

8014 literal slashes. 

8015 Some versions of azvk allow the form: 

8016 func name (args, ... ) { statements } 

8017 This has been deprecated by the authors of the language, who asked that it not be included in 

8018 IEEE Std. 1003.1-200x. 

8019 Historical implementations of azvk produce an error if a next statement is executed in a BEGIN 

8020 action, and cause azvk to terminate if a next statement is executed in an END action. This 

8021 behavior has not been documented, and it was not believed that it was necessary to standardize 

8022 it. 

8023 The specification of conversions between string and numeric values is much more detailed than 

8024 in the documentation of historical implementations or in the referenced The AWK Programming 

8025 Language. Although most of the behavior is designed to be intuitive, the details are necessary to 

8026 ensure compatible behavior from different implementations. This is especially important in 

8027 relational expressions since the types of the operands determine whether a string or numeric 
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8028 comparison is performed. From the perspective of an application writer, it is usually sufficient to 

8029 expect intuitive behavior and to force conversions (by adding zero or concatenating a null 

8030 string) when the type of an expression does not obviously match what is needed. The intent has 

8031 been to specify historical practice in almost all cases. The one exception is that, in historical 

8032 implementations, variables and constants maintain both string and numeric values after their 

8033 original value is converted by any use. This means that referencing a variable or constant can 

8034 have unexpected side effects. For example, with historical implementations the following 

8035 program: 

8036 { 

8037 a = " + 2 " 

8038 b = 2 

8039 if (NR % 2) 

8040 c = a + b 

8041 if (a == b) 

8042 print "numeric comparison" 

8043 else 

8044 print "string comparison" 

8045 } 

8046 would perform a numeric comparison (and output numeric comparison) for each odd- 

8047 numbered line, but perform a string comparison (and output string comparison) for each even- 

8048 numbered line. IEEE Std. 1003.1-200x ensures that comparisons will be numeric if necessary. 

8049 With historical implementations, the following program: 

8050 BEGIN { 

8051 OFMT = " %e" 

8052 print 3.14 

8053 OFMT = "%f" 

8054 print 3.14 

8055 } 

8056 would output "3.140000e + 00" twice, because in the second print statement the constant 

8057 "3.14" would have a string value from the previous conversion. IEEE Std. 1003.1-200x requires 

8058 that the output of the second print statement be "3.140000". The behavior of historical 

8059 implementations was seen as too unintuitive and unpredictable. 

8060 It was pointed out that with the rules contained in early drafts, the following script would print 

8061 nothing: 

8062 BEGIN { 

8063 y [ 1 . 5 ] = 1 

8064 OFMT = "%e" 

8065 print y [ 1.5 ] 

8066 } 

8067 Therefore, a new variable, CONVFMT, was introduced. The OFMT variable is now restricted to 

8068 affecting output conversions of numbers to strings and CONVFMT is used for internal 

8069 conversions, such as comparisons or array indexing. The default value is the same as that for 

8070 OFMT, so unless a program changes CONVFMT (which no historical program would do), it 

8071 will receive the historical behavior associated with internal string conversions. 

8072 The POSIX awk lexical and syntactic conventions are specified more formally than in other 

8073 sources. Again the intent has been to specify historical practice. One convention that may not be 

8074 obvious from the formal grammar as in other verbal descriptions is where <newline> characters 

8075 are acceptable. There are several obvious placements such as terminating a statement, and a 
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8076 backslash can be used to escape <newline> characters between any lexical tokens. In addition, 

8077 <newline> characters without backslashes can follow a comma, an open brace, a logical AND 

8078 operator ("&&"), a logical OR operator (" | | "), the do keyword, the else keyword, and the 

8079 closing parenthesis of an if, for, or while statement. For example: 

8080 { print $1, 

8081 $2 } 

8082 The requirement that azvk add a trailing <newline> character to the program argument text is to 

8083 simplify the grammar, making it match a text file in form. There is no way for an application or 

8084 test suite to determine whether a literal <newline> is added or whether awk simply acts as if it 

8085 did. 

8086 IEEE Std. 1003.1-200x requires several changes from historical implementations in order to 

8087 support internationalization. Probably the most subtle of these is the use of the decimal-point 

8088 character, defined by the LC_NUMERIC category of the locale, in representations of floating- 

8089 point numbers. This locale-specific character is used in recognizing numeric input, in converting 

8090 between strings and numeric values, and in formatting output. However, regardless of locale, 

8091 the period character (the decimal-point character of the POSIX locale) is the decimal-point 

8092 character recognized in processing awk programs (including assignments in command line 

8093 arguments). This is essentially the same convention as the one used in the ISO C standard. The 

8094 difference is that the C language includes the setlocale() function, which permits an application 

8095 to modify its locale. Because of this capability, a C application begins executing with its locale 

8096 set to the C locale, and only executes in the environment-specified locale after an explicit call to 

8097 setlocale(). However, adding such an elaborate new feature to the awk language was seen as 

8098 inappropriate for IEEE Std. 1003.1-200x. It is possible to execute an awk program explicitly in any 

8099 desired locale by setting the environment in the shell. 

8100 The undefined behavior resulting from NULs in extended regular expressions allows future 

8101 extensions for the GNU gazvk program to process binary data. 

8102 The behavior in the case of invalid azvk programs (including lexical, syntactic, and semantic 

8103 errors) is undefined because it was considered overly limiting on implementations to specify. In 

8104 most cases such errors can be expected to produce a diagnostic and a non-zero exit status. 

8105 However, some implementations may choose to extend the language in ways that make use of 

8106 certain invalid constructs. Other invalid constructs might be deemed worthy of a warning, but 

8107 otherwise cause some reasonable behavior. Still other constructs may be very difficult to detect 

8108 in some implementations. Also, different implementations might detect a given error during an 

8109 initial parsing of the program (before reading any input files) while others might detect it when 

8110 executing the program after reading some input. Implementors should be aware that diagnosing 

8111 errors as early as possible and producing useful diagnostics can ease debugging of applications, 

8112 and thus make an implementation more usable. 

8113 The unspecified behavior from using multi-character RS values is to allow possible future 

8114 extensions based on extended regular expressions used for record separators. Historical 

8115 implementations take the first character of the string and ignore the others. 

8116 Unspecified behavior when split {string, array ,<null>) is used is to allow a proposed future 

8117 extension that would split up a string into an array of individual characters. 

8118 Because the concatenation operation is represented by adjacent expressions rather than an 

8119 explicit operator, it is often necessary to use parentheses to enforce the proper evaluation 

8120 precedence. 

8121 In the context of the getline function, equally good arguments for different precedences of the I 

8122 and < operators can be made. Historical practice has been that: 
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8123 get line < "a" "b" 

8124 is parsed as: 

8125 ( get line < "a" ) "b" 

8126 although many would argue that the intent was that the file ab should be read. However: 

8127 get line < "x" + 1 

8128 parses as: 

8129 get line < ( "x" + 1 ) 

8130 Similar problems occur with the I version of getline, particularly in combination with $. For 

8131 example: 

8132 $"echo hi" | getline 

8133 (This situation is particularly problematic when used in a print statement, where the I getline 

8134 part might be a redirection of the print.) 

8135 Since in most cases such constructs are not (or at least should not) be used (because they have a 

8136 natural ambiguity for which there is no conventional parsing), the meaning of these constructs 

8137 has been made explicitly unspecified. (The effect is that a portable application that runs into the 

8138 problem must parenthesize to resolve the ambiguity.) There appeared to be few if any actual 

8139 uses of such constructs. 

8140 Grammars can be written that would cause an error under these circumstances. Where 

8141 backwards compatibility is not a large consideration, implementors may wish to use such 

8142 grammars. 

8143 Some historical implementations have allowed some built-in functions to be called without an 

8144 argument list, the result being a default argument list chosen in some "reasonable" way. Use of 

8145 length as a synonym for length($0) is the only one of these forms that is thought to be widely 

8146 known or widely used; this particular form is documented in various places (for example, most 

8147 historical awk reference pages, although not in the referenced The AWK Programming Language) 

8148 as legitimate practice. With this exception, default argument lists have always been 

8149 undocumented and vaguely defined, and it is not at all clear how (or if) they should be 

8150 generalized to user-defined functions. They add no useful functionality and preclude possible 

8151 future extensions that might need to name functions without calling them. Not standardizing 

8152 them seems the simplest course. The standard developers considered that length merited special 

8153 treatment, however, since it has been documented in the past and sees possibly substantial use 

8154 in historical programs. Accordingly, this usage has been made legitimate, for backwards 

8155 compatibility, but marked obsolescent in hopes that it can eventually be removed from the 

8156 language. 

8157 In sub and gsub, if repl is a string literal (the lexical token STRING), then two consecutive 

8158 backslash characters should be used in the string to ensure a single backslash will precede the 

8159 ampersand when the resultant string is passed to the function. (For example, to specify one 

8160 literal ampersand in the replacement string, use gsub(ERE, " \ \ &").) 

8161 Historically the only special character in the repl argument of sub and gsub string functions was 

8162 the ampersand (' &') character and preceding it with the backslash character was used to turn 

8163 off its special meaning. 

8164 The description in the ISO POSIX-2:1993 standard introduced behavior such that the backslash 

8165 character was another special character and it was unspecified whether there were any other 

8166 special characters. This description introduced several portability problems, some of which are 

8167 described below, and so it has been replaced with the more historical description. Some of the 
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8168 problems include: 

8169 • Historically, to create the replacement string, a script could use gsub(ERE, " \ \&"), but with 

8170 the ISO POSIX-2:1993 standard wording, it was necessary to use gsub(ERE, "\\\\&"). 

8171 Backslash characters are doubled here because all string literals are subject to lexical analysis, 

8172 which would reduce each pair of backslash characters to a single backslash before being 

8173 passed to gsub. 

8174 • Since it was unspecified what the special characters were, for portable scripts to guarantee 

8175 that characters are printed literally, each character had to be preceded with a backslash. (For 

8176 example, a portable script had to use gsub(ERE, "\\h\\i") to produce a replacement string 

8177 of "hi".) 

8178 The description for comparisons in the ISO POSIX-2:1993 standard did not properly describe 

8179 historical practice because of the way numeric strings are compared as numbers. The current 

8180 rules cause the following code: 

8181 if (0 == "000") 

8182 print "strange, but true" 

8183 else 

8184 print "not true" 

8185 to do a numeric comparison, causing the if to succeed. It should be intuitively obvious that this 

8186 is incorrect behavior, and indeed, no historical implementation of azvk actually behaves this way. 

8187 To fix this problem, the definition of numeric string was enhanced to include only those values 

8188 obtained from specific circumstances (mostly external sources) where it is not possible to 

8189 determine unambiguously whether the value is intended to be a string or a numeric. 

8190 Variables that are assigned to a numeric string shall also be treated as a numeric string. (For 

8191 example, the notion of a numeric string can be propagated across assignments.) In comparisons, 

8192 all variables having the uninitialized value are to be treated as a numeric operand evaluating to 

8193 the numeric value zero. 

8194 Uninitialized variables include all types of variables including scalars, array elements, and fields. 

8195 The definition of an uninitialized value in Variables and Special Variables on page 193 is 

8196 necessary to describe the value placed on uninitialized variables and on fields that are valid (for 

8197 example, < $NF) but have no characters in them and to describe how these variables are to be 

8198 used in comparisons. A valid field, such as $1, that has no characters in it can be obtained by 

8199 from an input line of "\t\t" when FS=' \t' . Historically, the comparison ($1<10) was done 

8200 numerically after evaluating $1 to the value zero. 

8201 The phrase "... also shall have the numeric value of the numeric string" was removed from 

8202 several sections of the ISO POSIX-2:1993 standard because is specifies an unnecessary 

8203 implementation detail. It is not necessary for IEEE Std. 1003.1-200x to specify that these objects 

8204 be assigned two different values. It is only necessary to specify that these objects may evaluate 

8205 to two different values depending on context. 

8206 The description of numeric string processing is based on the behavior of the atof( ) function in 

8207 the ISO C standard. While it is not a requirement for an implementation to use this function, 

8208 many historical implementations of azvk do. In the ISO C standard, floating-point constants use a 

8209 period as a decimal point character for the language itself, independent of the current locale, but 

8210 the atof() function and the associated strtod() function use the decimal point character of the 

8211 current locale when converting strings to numeric values. Similarly in azvk, floating point 

8212 constants in an azvk script use a period independent of the locale, but input strings use the 

8213 decimal point character of the locale. 
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8214 FUTURE DIRECTIONS 

8215 None. 

8216 SEE ALSO 

8217 grep, lex, sed, the System Interfaces volume of IEEE Std. 1003.1-200x, atof( ), setlocale( ), strtod () 

8218 CHANGE HISTORY 

8219 First released in Issue 2. 

8220 Issue 4 

8221 Aligned with the ISO/IEC 9945-2:1993 standard. 

8222 Issue 4, Version 2 

8223 The EXAMPLES section is corrected as follows: 

8224 • In Example 10, the braces are removed. 

8225 • In Example 17, the invocation of printf is corrected. 

8226 Issue 5 

8227 FUTURE DIRECTIONS section added. 

8228 Issue 6 

8229 The azvk utility is aligned with the IEEE P1003.2b draft standard. 

8230 The normative text is reworded to avoid use of the term "must” for application requirements. 
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8231 NAME 

8232 basename — return non-directory portion of a path name 

8233 SYNOPSIS 

8234 basename string [ suffix] 


8235 DESCRIPTION 

8236 The string operand shall be treated as a path name, as defined in the System Interface Definitions I 

8237 volume of IEEE Std. 1003.1-200x, Section 3.272, Path Name. The string string shall be converted I 

8238 to the file name corresponding to the last path name component in string and then the suffix 

8239 string suffix, if present, shall be removed. This shall be done by performing actions equivalent to 

8240 the following steps in order: 


8241 

8242 

8243 

8244 

8245 

8246 


1. If string is a null string, it is unspecified whether the resulting string is ' .' or a null string. 
In either case, skip steps 2 through 6. 

2. If string is "//", it is implementation-dependent whether steps 3 to 6 are skipped or 
processed. 

3. If string consists entirely of slash characters, string shall be set to a single slash character. In 
this case, skip steps 4 to 6. 


8247 

8248 

8249 


4. If there are any trailing slash characters in string, they shall be removed. 

5. If there are any slash characters remaining in string, the prefix of string up to and including 
the last slash character in string shall be removed. 


8250 

8251 

8252 

8253 


6. If the suffix operand is present, is not identical to the characters remaining in string, and is 
identical to a suffix of the characters remaining in string, the suffix suffix shall be removed 
from string. Otherwise, string is modified by this step. It shall not be considered an error if 
suffix is not found in string. 


8254 The resulting string shall be written to standard output. 


8255 OPTIONS 

8256 None. 


8257 OPERANDS 

8258 The following operands shall be supported: 

8259 string A string. 

8260 suffix A string. 

8261 STDIN 

8262 Not used. 


8263 INPUT FILES 

8264 None. 


8265 ENVIRONMENT VARIABLES 

8266 The following environment variables shall affect the execution of basename: 


8267 

8268 

8269 

8270 

8271 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


8272 LC_ALL If set to a non-empty string value, override the values of all the other 

8273 internationalization variables. 
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8274 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

8275 characters (for example, single-byte as opposed to multi-byte characters in 

8276 arguments). 

8277 LC_MESSAGES 

8278 Determine the locale that should be used to affect the format and contents of 

8279 diagnostic messages written to standard error. 

8280 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

8281 ASYNCHRONOUS EVENTS 

8282 Default. 

8283 STDOUT 

8284 The basename utility shall write a line to the standard output in the following format: 

8285 "%s\n", <resulting string> 

8286 STDERR 

8287 Used only for diagnostic messages. 

8288 OUTPUT FILES 

8289 None. 

8290 EXTENDED DESCRIPTION 

8291 None. 

8292 EXIT STATUS 

8293 The following exit values shall be returned: 

8294 0 Successful completion. 

8295 >0 An error occurred. 

8296 CONSEQUENCES OF ERRORS 

8297 Default. 

8298 APPLICATION USAGE 

8299 The definition of pathname specifies implementation-dependent behavior for path names starting 

8300 with two slash characters. Therefore, applications shall not arbitrarily add slashes to the I 

8301 beginning of a path name unless they can ensure that there are more or less than two or are 

8302 prepared to deal with the implementation-dependent consequences. 

8303 EXAMPLES 

8304 If the string string is a valid path name: 

8305 $ (basename "string") 

8306 produces a file name that could be used to open the file named by string in the directory 

8307 returned by: 

8308 $ (dirname "string") 

8309 If the string string is not a valid path name, the same algorithm is used, but the result need not be 

8310 a valid file name. The basename utility is not expected to make any judgements about the validity 

8311 of string as a path name; it just follows the specified algorithm to produce a result string. 

8312 The following shell script compiles /usr/src/cmd/cat.c and moves the output to a file named cat 

8313 in the current directory when invoked with the argument /usr/src/cmd/cat or with the argument 

8314 /usr/src/cmd/cat.c: 
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8315 c89 $ (dirname " $1 ")/$ (basename "$1" ,c).c 

8316 mv a. out $ (basename "$1" .c) 

8317 RATIONALE 

8318 The behaviors of basename and dirname have been coordinated so that when string is a valid path 

8319 name: 

8320 $ (basename "string") 

8321 would be a valid file name for the file in the directory: 

8322 $ (dirname "string") 

8323 This would not work for the early proposal versions of these utilities due to the way it specified 

8324 handling of trailing slashes. 

8325 Since the definition of pathname specifies implementation-dependent behavior for path names 

8326 starting with two slash characters, this volume of IEEE Std. 1003.1-200x specifies similar 

8327 implementation-dependent behavior for the basename and dirname utilities. 

8328 FUTURE DIRECTIONS 

8329 None. 

8330 SEE ALSO 

8331 dirname, Section 2.5 on page 43 

8332 CHANGE HISTORY 

8333 First released in Issue 2. 

8334 Issue 4 

8335 Aligned with the ISO/IEC 9945-2:1993 standard. 

8336 Issue 6 

8337 PASC Interpretation 1003.2-92 #164 has been applied. 

8338 The normative text is reworded to avoid use of the term "must” for application requirements. 
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8339 NAME 

8340 batch — schedule commands to be executed in a batch queue I 

8341 SYNOPSIS 

8342 UP ba t ch 

8343 

8344 DESCRIPTION 

8345 The batch utility shall read commands from standard input and schedule them for execution in a I 

8346 batch queue. It shall be the equivalent of the command: I 

8347 at —q b — m now 

8348 where queue b is a special at queue, specifically for batch jobs. Batch jobs shall be submitted to 

8349 the batch queue with no time constraints and shall be run by the system using algorithms, based 

8350 on unspecified factors, that may vary with each invocation of batch. 

8351 xsi Users are permitted to use batch if their name appears in the file /usr/lib/cron/at.allow. If that file 

8352 does not exist, the file /usr/lib/cron/at.deny is checked to determine whether the user should be 

8353 denied access to batch. If neither file exists, only a process with the appropriate privileges is 

8354 allowed to submit a job. If only at.deny exists and is empty, global usage is permitted. The 

8355 at.allow and at.deny files consist of one user name per line. 

8356 OPTIONS 

8357 None. 

8358 OPERANDS 

8359 None. 


8360 STDIN 

8361 The standard input shall be a text file consisting of commands acceptable to the shell command I 

8362 language described in Chapter 2 on page 35. 


8363 INPUT FILES 

8364 xsi The text files /usr/lib/cron/at.allow and /usr/lib/cron/at.deny contain user names, one per line, of 

8365 users who are, respectively, authorized or denied access to the at and batch utilities. 


8366 ENVIRONMENT VARIABLES 

8367 The following environment variables shall affect the execution of batch: 


8368 

8369 

8370 

8371 

8372 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


8373 LC_ALL If set to a non-empty string value, override the values of all the other 

8374 internationalization variables. 


8375 

8376 

8377 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


8378 

8379 

8380 

8381 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 


8382 


LC_TIME Determine the format and contents for date and time strings written by batch. 
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8383 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


8384 

8385 

8386 

8387 

8388 


SHELL Determine the name of a command interpreter to be used to invoke the at-job. If 
the variable is unset or null, sh shall be used. If it is set to a value other than a name 
for sh, the implementation shall do one of the following: use that shell; use sh; use 
the login shell from the user database; any of the preceding accompanied by a 
warning diagnostic about which was chosen. 


8389 

8390 

8391 

8392 

8393 


TZ Determine the timezone. The job shall be submitted for execution at the time 

specified by timespec or -t time relative to the timezone specified by the TZ 
variable. If timespec specifies a timezone, it overrides TZ. If timespec does not 
specify a timezone and TZ is unset or null, an unspecified default timezone shall 
be used. 


8394 ASYNCHRONOUS EVENTS 

8395 Default. 


8396 STDOUT 

8397 When standard input is a terminal, prompts of unspecified format for each line of the user input 

8398 described in the STDIN section may be written to standard output. 

8399 STDERR 

8400 The following shall be written to standard error when a job has been successfully submitted: 

8401 "job %s at %s\n", at_job_id, <date> 

8402 where date shall be equivalent in format to the output of: 

8403 date +"%a %b %e %T %Y" 

8404 The date and time written shall be adjusted so that they appear in the timezone of the user (as 

8405 determined by the TZ variable). 

8406 Neither this, nor warning messages concerning the selection of the command interpreter, are 

8407 considered a diagnostic that changes the exit status. 

8408 Diagnostic messages, if any, shall be written to standard error. 

8409 OUTPUT FILES 

8410 None. 


8411 EXTENDED DESCRIPTION 

8412 None. 


8413 EXIT STATUS 

8414 The following exit values shall be returned: 

8415 0 Successful completion. 

8416 >0 An error occurred. 


8417 CONSEQUENCES OF ERRORS 

8418 The job shall not be scheduled. 


226 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


batch 


8419 APPLICATION USAGE 

8420 It may be useful to redirect standard output within the specified commands. 

8421 Application writers should note that this utility need not be provided on systems that do not 

8422 support the User Portability Utilities option. 

8423 EXAMPLES 

8424 1. 

8425 

8426 

8427 

8428 2. 

8429 

8430 

8431 RATIONALE 

8432 Early proposals described batch in a manner totally separated from at, even though the historical 

8433 model treated it almost as a synonym for at -qb. A number of features were added to list and 

8434 control batch work separately from those in at. Upon further reflection, it was decided that the 

8435 benefit of this did not merit the change to the historical interface. 

8436 The -m option was included on the equivalent at command because it is historical practice to 

8437 mail results to the submitter, even if all job-produced output is redirected. As explained in the 

8438 RATIONALE for at, the now keyword submits the job for immediate execution (after scheduling 

8439 delays), despite some historical systems where at now would have been considered an error. 

8440 FUTURE DIRECTIONS 

8441 None. 

8442 SEE ALSO 

8443 at 

8444 CHANGE HISTORY 

8445 First released in Issue 2. 


This sequence can be used at a terminal: 

batch 

sort < file >outfile 
EOT 

This sequence, which demonstrates redirecting standard error to a pipe, is useful in a 
command procedure (the sequence of output redirection specifications is significant): 

batch <<! diff filel file2 2>&1 >outfile I mailx mygroup ! 


8446 

8447 

8448 

8449 

8450 

8451 

8452 


Issue 4 

Format reorganized and separated from the at description. 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The NAME is changed to align with the IEEE P1003.2b draft standard. 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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8453 NAME 

8454 be — arbitrary-precision arithmetic language 

8455 SYNOPSIS 

8456 be [—1] [file . . .] 

8457 DESCRIPTION 

8458 The be utility shall implement an arbitrary precision calculator. It shall take input from any files 

8459 given, then read from the standard input. If the standard input and standard output to be are 

8460 attached to a terminal, the invocation of be shall be considered to be interactive, causing 

8461 behavioral constraints described in the following sections. 

8462 OPTIONS 

8463 The be utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

8464 Section 12.2, Utility Syntax Guidelines. I 

8465 The following option shall be supported: 

8466 -1 (The letter ell.) Define the math functions and initialize scale to 20, instead of the 

8467 default zero; see the EXTENDED DESCRIPTION section. 

8468 OPERANDS 

8469 The following operand shall be supported: 

8470 file A path name of a text file containing be program statements. After all files have 

8471 been read, be shall read the standard input. 

8472 STDIN 

8473 See the INPUT FILES section. 


8474 INPUT FILES 

8475 Input files shall be text files containing a sequence of comments, statements, and function I 

8476 definitions that shall be executed as they are read. 


8477 ENVIRONMENT VARIABLES 

8478 The following environment variables shall affect the execution of be: 


8479 

8480 

8481 

8482 

8483 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


8484 

8485 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


8486 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

8487 characters (for example, single-byte as opposed to multi-byte characters in 

8488 arguments and input files). 

8489 LC_MESSAGES 

8490 Determine the locale that should be used to affect the format and contents of 

8491 diagnostic messages written to standard error. 

8492 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

8493 ASYNCHRONOUS EVENTS 

8494 Default. 
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8495 STDOUT 

8496 The output of the be utility shall be controlled by the program read, and consist of zero or more 

8497 lines containing the value of all executed expressions without assignments. The radix and 

8498 precision of the output shall be controlled by the values of the obase and scale variables; see the 

8499 EXTENDED DESCRIPTION section. 

8500 STDERR 

8501 Used only for diagnostic messages. 

8502 OUTPUT FILES 

8503 None. 

8504 EXTENDED DESCRIPTION 

8505 Grammar 

8506 The grammar in this section and the lexical conventions in the following section shall together 


8507 

8508 

8509 

8510 

describe the syntax for be programs. The general conventions for this style of grammar are 
described in Section 1.10 on page 24. A valid program can be represented as the non-terminal 
symbol program in the grammar. This formal syntax shall take precedence over the text syntax 
description. 

8511 

%token 

EOF NEWLINE STRING LETTER NUMBER 

8512 

%token 

MUL_OP 


8513 

/* 

' * r r / t 

r It 

' %' */ 

8514 

%token 

AS SIGN_OP 


8515 

/* 

r — r r j__ r 

r ' 

' _=' r -k — r t /— t t o,— t r ~ — r * / 

r r r / r ° r / 

8516 

%token 

REL_OP 


8517 

/* 

'<= 

V 

II 

II 

A 

V 

X- 

8518 

%token 

INCR_DECR 

8519 

/* 

', '— 

' */ 

8520 

%token 

Define 

Break Quit Length 

8521 

/* 

' define', 

'break', 'quit', 'length' */ 

8522 

%token 

Return 

For If While Sqrt 

8523 

/* 

' return', 

'for', 'if', 'while', 'sqrt' */ 

8524 

%token 

Scale 

Ibase Obase Auto 

8525 

/* 

' scale', 

'ibase', 'obase', 'auto' */ 

8526 

%start 

program 


8527 

"o "o 



8528 

program 


: EOF 

8529 



I input_item program 

8530 



t 

8531 

input_item 

: semicolon_list NEWLINE 

8532 



I function 

8533 



t 

8534 

semicolon. 

_list 

: /* empty */ 

8535 



I statement 

8536 



| semicolon_list ';' statement 

8537 



| semicolon_list '; ' 
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8538 



r 


8539 


statement_list 


/* empty */ 

8540 



1 

statement 

8541 



1 

statement_list NEWLINE 

8542 



1 

statement_list NEWLINE statement 

8543 



1 

statement_list ';' 

8544 



I 

statement_list ';' statement 

8545 



r 


8546 


statement 


expression 

8547 



1 

STRING 

8548 



1 

Break 

8549 



1 

Quit 

8550 



1 

Return 

8551 



1 

Return '(' return_expression ')' 

8552 



1 

For '(' expression 

8553 




relational_expression ' ; ' 

8554 




expression ')' statement 

8555 



1 

If '(' relational_expression ')' statement 

8556 



1 

While '(' relational_expression ')' statement 

8557 



1 

' {' statement_list ' }' 

8558 



r 


8559 


function 


Define LETTER '(' opt_parameter_list ')' 

8560 




'{' NEWLINE opt_auto_define_list 

8561 




statement_list '}' 

8562 



r 


8563 


opt_parameter_list 


/* empty */ 

8564 



1 

parameter_list 

8565 



r 


8566 


parameter_list 


LETTER 

8567 



1 

define_list ',' LETTER 

8568 



r 


8569 


opt_auto_define_list 


/* empty */ 

8570 



1 

Auto define_list NEWLINE 

8571 



1 

Auto define_list ' ; ' 

8572 



r 


8573 


define_list 


LETTER 

8574 



1 

LETTER ' [' ' ] ' 

8575 



1 

define_list ' , ' LETTER 

8576 



1 

define_list LETTER '[' ']' 

8577 



i 


8578 


opt_argument_list 


/* empty */ 

8579 



1 

argument_list 

8580 



r 


8581 


argument_list 


expression 

8582 



1 

LETTER ' [' ']' ' argument_list" 

8583 



r 
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8584 relational_expression : expression 


8585 

8586 

8587 return_expression 

8588 

8589 


| expression REL_OP expression 

r 

: /* empty */ 

| expression 


8590 expression 

8591 

8592 

8593 

8594 

8595 

8596 

8597 

8598 

8599 

8600 
8601 
8602 

8603 

8604 

8605 


: named_expression 
| NUMBER 

I ' (' expression ')' 

| LETTER ' (' opt_argument_list ')' 

I 'expression 
| expression '+' expression 
| expression 'expression 
| expression MUL_OP expression 
| expression '"' expression 
| INCR_DECR named_expression 
I named_expression INCR_DECR 
I named_expression ASSIGN_OP expression 
I Length ' (' expression ')' 

I Sqrt '(' expression ')' 

I Scale '(' expression ')' 


8606 named_expression 

8607 

8608 

8609 

8610 
8611 


: LETTER 

| LETTER '[' expression ']' 
I Scale 
I Ibase 
I Obase 


8612 Lexical Conventions in be 

8613 The lexical conventions for be programs, with respect to the preceding grammar, shall be as 

8614 follows: 


8615 1. Except as noted, be shall recognize the longest possible token or delimiter beginning at a 

8616 given point. 


8617 

8618 
8619 


2. A comment shall consist of any characters beginning with the two adjacent characters 
"/*" and terminated by the next occurrence of the two adjacent characters 
Comments shall have no effect except to delimit lexical tokens. 


8620 

8621 

8622 

8623 

8624 

8625 

8626 
8627 


3. The <newline> character shall be recognized as the token NEWLINE. 

4. The token STRING shall represent a string constant; it shall consist of any characters 
beginning with the double-quote character (' "') and terminated by another occurrence of 
the double-quote character. The value of the string is the sequence of all characters 
between, but not including, the two double-quote characters. All characters shall be taken 
literally from the input, and there is no way to specify a string containing a double-quote 
character. The length of the value of each string shall be limited to |BC_STRING_MAX} 
bytes. 


8628 5. A <blank> character shall have no effect except as an ordinary character if it appears 

8629 within a STRING token, or to delimit a lexical token other than STRING. 
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6. The combination of a backslash character immediately followed by a <newline> character 
shall have no effect other than to delimit lexical tokens with the following exceptions: 

• It shall be interpreted as the character sequence "\<newline>" in STRING tokens. 

• It shall be ignored as part of a multi-line NUMBER token. 

7. The token NUMBER shall represent a numeric constant. It shall be recognized by the 
following grammar: 

NUMBER : integer 

I ' integer 
I integer ' .' 

I integer '.' integer 


integer 


: digit 

I integer digit 


digit :0|1|2|3|4|5|6|7 
|8|9|A|B|C|D|E|F 

r 

8. The value of a NUMBER token shall be interpreted as a numeral in the base specified by 
the value of the internal register ibase (described below). Each of the digit characters shall 
have the value from 0 to 15 in the order listed here, and the period character shall represent 
the radix point. The behavior is undefined if digits greater than or equal to the value of 
ibase appear in the token. However, note the exception for single-digit values being 
assigned to ibase and obase themselves, in Operations in be on page 233. 


9. The following keywords shall be recognized as tokens: 

auto ibase length return 

break if obase scale 

define for quit sqrt 


while 


10. Any of the following characters occurring anywhere except within a keyword shall be 
recognized as the token LETTER: 

abedefghi jklmnopqrstuvwxyz 

11. The following single-character and two-character sequences shall be recognized as the 
token ASSIGN OP: 


12. If an ' = ' character, as the beginning of a token, is followed by a character with no 
intervening delimiter, the behavior is undefined. 

13. The following single-characters shall be recognized as the token MUL_OP: 


14. The following single-character and two-character sequences shall be recognized as the 
token REL_OP: 


15. The following two-character sequences shall be recognized as the token INCR_DECR: 
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8671 ++ — 

8672 16. The following single characters shall be recognized as tokens whose names are the 

8673 character: 

8674 <newline> (),+ — ; []'"{} 

8675 1 7. The token EOF is returned when the end of input is reached. 

8676 Operations in be 

8677 There are three kinds of identifiers: ordinary identifiers, array identifiers, and function 

8678 identifiers. All three types consist of single lowercase letters. Array identifiers shall be followed 

8679 by square brackets (" [ ] "). An array subscript is required except in an argument or auto list. 

8680 Arrays are singly dimensioned and can contain up to |BC_DIM_MAX} elements. Indexing shall 

8681 begin at zero so an array is indexed from 0 to |BC_DIM_MAX}-1. Subscripts shall be truncated I 

8682 to integers. The application shall ensure that function identifiers are followed by parentheses, I 

8683 possibly enclosing arguments. The three types of identifiers do not conflict. I 

8684 The following table summarizes the rules for precedence and associativity of all operators. 

8685 Operators on the same line shall have the same precedence; rows are in order of decreasing 

8686 precedence. 


8687 Table 4-3 Operators in be 


8688 

Operator 

Associativity 

8689 

+ +,- 

N/A 

8690 

unary — 

N/A 

8691 

A 

Right to left 

8692 

*, t, % 

Left to right 

8693 

+, binary — 

Left to right 

8694 

= t ~ >t= r ~ = r * = r / ~ r = r = 

Right to left 

8695 

==, <=, >=, !=, <, > 

None 


8696 Each expression or named expression has a scale, which is the number of decimal digits that 

8697 shall be maintained as the fractional portion of the expression. 

8698 Named expressions are places where values are stored. Named expressions shall be valid on the 

8699 left side of an assignment. The value of a named expression shall be the value stored in the place 

8700 named. Simple identifiers and array elements are named expressions; they have an initial value 

8701 of zero and an initial scale of zero. 

8702 The internal registers scale, ibase, and obase are all named expressions. The scale of an 

8703 expression consisting of the name of one of these registers shall be zero; values assigned to any 

8704 of these registers are truncated to integers. The scale register shall contain a global value used in 

8705 computing the scale of expressions (as described below). The value of the register scale is 

8706 limited to 0 < scale < |BC_SCALE_MAX} and shall have a default value of zero. The ibase and 

8707 obase registers are the input and output number radix, respectively. The value of ibase shall be 

8708 limited to: 

8709 2 < ibase < 16 

8710 The value of obase shall be limited to: 

8711 2 < obase < {BC_BASE_MAX} 

8712 When either ibase or obase is assigned a single digit value from the list in Lexical Conventions 

8713 in be on page 231, the value shall be assumed in hexadecimal. (For example, ibase=A sets to 
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base ten, regardless of the current ibase value.) Otherwise, the behavior is undefined when 
digits greater than or equal to the value of ibase appear in the input. Both ibase and obase shall 
have initial values of 10. 

Internal computations shall be conducted as if in decimal, regardless of the input and output 
bases, to the specified number of decimal digits. When an exact result is not achieved, (for 
example, scale=0; 3.2/1) the result shall be truncated. 

For all values of obase specified by this volume of IEEE Std. 1003.1-200x, be shall output numeric I 
values by performing each of the following steps in order: I 

1. If the value is less than zero, a hyphen (' —') character shall be output. 

2. One of the following is output, depending on the numerical value: 

• If the absolute value of the numerical value is greater than or equal to one, the integer 

portion of the value shall be output as a series of digits appropriate to obase (as I 
described below) most significant digit first. The most significant non-zero digit shall I 
be output next, followed by each successively less significant digit. I 

• If the absolute value of the numerical value is less than one but greater than zero and 
the scale of the numerical value is greater than zero, it is unspecified whether the 
character 0 is output. 

• If the numerical value is zero, the character 0 shall be output. 

3. If the scale of the value is greater than zero and the numeric value is not zero, a period I 
character shall be output, followed by a series of digits appropriate to obase (as described I 
below) representing the most significant portion of the fractional part of the value. If s 
represents the scale of the value being output, the number of digits output shall be s if 
obase is 10, less than or equal to s if obase is greater than 10, or greater than or equal to s if 
obase is less than 10. For obase values other than 10, this should be the number of digits 
needed to represent a precision of 10 s . 

For obase values from 2 to 16, valid digits are the first obase of the single characters: 


01234567 


9 A B C D E F 


which represent the values zero to 15, inclusive, respectively. 

For bases greater than 16, each digit shall be written as a separate multi-digit decimal number. 
Each digit except the most significant fractional digit shall be preceded by a single <space> 
character. For bases from 17 to 100, be shall write two-digit decimal numbers; for bases from 101 
to 1000, three-digit decimal strings, and so on. For example, the decimal number 1024 in base 25 
would be written as: 

A01A15A24 

in base 125, as: 

A008A024 

Very large numbers shall be split across lines with 70 characters per line in the POSIX locale; 
other locales may split at different character boundaries. Lines that are continued shall end with 
a backslash (' V ). 

A function call shall consist of a function name followed by parentheses containing a comma- 
separated list of expressions, which are the function arguments. A whole array passed as an 
argument shall be specified by the array name followed by empty square brackets. All function 
arguments shall be passed by value. As a result, changes made to the formal parameters shall 
have no effect on the actual arguments. If the function terminates by executing a return 
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8758 statement, the value of the function shall be the value of the expression in the parentheses of the 

8759 return statement or shall be zero if no expression is provided or if there is no return statement. 

8760 The result of sqrt (expression) shall be the square root of the expression. The result shall be 

8761 truncated in the least significant decimal place. The scale of the result shall be the scale of the 

8762 expression or the value of scale, whichever is larger. 

8763 The result of length (expression) shall be the total number of significant decimal digits in the 

8764 expression. The scale of the result shall be zero. 

8765 The result of seal e(expression) shall be the scale of the expression. The scale of the result shall be 

8766 zero. 

8767 A numeric constant shall be an expression. The scale shall be the number of digits that follow the 

8768 radix point in the input representing the constant, or zero if no radix point appears. 

8769 The sequence ( expression ) shall be an expression with the same value and scale as expression. 

8770 The parentheses can be used to alter the normal precedence. 

8771 The semantics of the unary and binary operators are as follows: 

8772 -expression 

8773 The result shall be the negative of the expression. The scale of the result shall be the scale of 

8774 expression. 

8775 The unary increment and decrement operators shall not modify the scale of the named 

8776 expression upon which they operate. The scale of the result shall be the scale of that named 

8777 expression. 

8778 ++named-expression 

8779 The named expression shall be incremented by one. The result shall be the value of the 

8780 named expression after incrementing. 

8781 — named-expression 

8782 The named expression shall be decremented by one. The result shall be the value of the 

8783 named expression after decrementing. 

8784 named-expression++ 

8785 The named expression shall be incremented by one. The result shall be the value of the 

8786 named expression before incrementing. 

8787 named-expression — 

8788 The named expression shall be decremented by one. The result shall be the value of the 

8789 named expression before decrementing. 

8790 The exponentiation operator, circumflex (' "'), shall bind right to left. 

8791 expression" expression 

8792 The result shall be the first expression raised to the power of the second expression. If the 

8793 second expression is not an integer, the behavior is undefined. If a is the scale of the left 

8794 expression and b is the absolute value of the right expression, the scale of the result shall be: 

8795 if b >= 0 min (a * b, max (scale, a)) if b < 0 scale 

8796 The multiplicative operators shall bind left to right. 

8797 expression* expression 

8798 The result shall be the product of the two expressions. If a and b are the scales of the two 

8799 expressions, then the scale of the result shall be: 


Commands and Utilities, Issue 6 


235 



be 


Utilities 


8800 min (a+b, max (scale, a, b) ) 

8801 expression/expression 

8802 The result shall be the quotient of the two expressions. The scale of the result shall be the 

8803 value of scale. 

8804 expression%expression 

8805 For expressions a and b, a%b shall be evaluated equivalent to the steps: 

8806 1. Compute a/b to current scale. 

8807 2. Use the result to compute: 

8808 a - (a/b) * b 

8809 to scale: 

8810 max (scale + scale (b) , scale (a) ) 

8811 The scale of the result shall be: 


8812 max (scale + scale (b) , scale (a) ) 

8813 When scale is zero, the ' %' operator is the mathematical remainder operator. 

8814 The additive operators shall bind left to right. 

8815 expression+expression 

8816 The result shall be the sum of the two expressions. The scale of the result shall be the 

8817 maximum of the scales of the expressions. 

8818 expression-expression 

8819 The result shall be the difference of the two expressions. The scale of the result shall be the 

8820 maximum of the scales of the expressions. 

8821 The assignment operators ('=', "+=", "*=", "/ = ", "%=", shall bind right to left. 

8822 named-expression=expression 

8823 This expression results in assigning the value of the expression on the right to the named 

8824 expression on the left. The scale of both the named expression and the result shall be the 

8825 scale of expression. 

8826 The compound assignment forms: 

8827 named-expression <operator>= expression 

8828 shall be equivalent to: 

8829 named-expression=named~expression <operator> expression 

8830 except that the named-expression shall be evaluated only once. 

8831 Unlike all other operators, the relational operators (' <', ' , "<=", ">=", "==", " !=") shall be 

8832 only valid as the object of an if, while, or inside a for statement. 

8833 expressionl<expression2 

8834 The relation shall be true if the value of expressionl is strictly less than the value of 

8835 expression2. 

8836 expressionl>expression2 

8837 The relation shall be true if the value of expressionl is strictly greater than the value of 

8838 expression2. 
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8839 expressionl<=expression2 

8840 The relation shall be true if the value of expressionl is less than or equal to the value of 

8841 expression2. 

8842 expressionl>=expression2 

8843 The relation shall be true if the value of expressionl is greater than or equal to the value of 

8844 expression2. 

8845 expressionl= =expression2 

8846 The relation shall be true if the values of expressionl and expression2 are equal. 

8847 expressionl\=expression2 

8848 The relation shall be true if the values of expressionl and expression2 are unequal. 

8849 There are only two storage classes in be, global and automatic (local). Only identifiers that are I 

8850 local to a function need be declared with the auto command. The arguments to a function shall I 

8851 be local to the function. All other identifiers are assumed to be global and available to all 

8852 functions. All identifiers, global and local, have initial values of zero. Identifiers declared as auto 

8853 shall be allocated on entry to the function and released on returning from the function. They 

8854 therefore do not retain values between function calls. Auto arrays shall be specified by the array 

8855 name followed by empty square brackets. On entry to a function, the old values of the names 

8856 that appear as parameters and as automatic variables shall be pushed onto a stack. Until the 

8857 function returns, reference to these names shall refer only to the new values. 

8858 References to any of these names from other functions that are called from this function also 

8859 refer to the new value until one of those functions uses the same name for a local variable. 

8860 When a statement is an expression, unless the main operator is an assignment, execution of the 

8861 statement shall write the value of the expression followed by a <newline> character. 

8862 When a statement is a string, execution of the statement shall write the value of the string. 

8863 Statements separated by semicolons or <newline> characters shall be executed sequentially. In 

8864 an interactive invocation of be, each time a <newline> character is read that satisfies the 

8865 grammatical production: 

8866 input_item : semicolon_list NEWLINE 

8867 the sequential list of statements making up the semicolon list shall be executed immediately 

8868 and any output produced by that execution shall be written without any delay due to buffering. 

8869 In an if statement (if (relation) statement), the statement shall be executed if the relation is true. 

8870 The while statement (whil e(relation) statement) implements a loop in which the relation is tested; 

8871 each time the relation is true, the statement shall be executed and the relation retested. When the 

8872 relation is false, execution shall resume after statement. 

8873 A for statement for (expression ; relation ; expression) statement) shall be the same as: 

8874 first-expression 

8875 while ( relation) { 

8876 statement 

8877 last-expression 

8878 } 

8879 The application shall ensure that all three expressions are present. I 

8880 The break statement shall cause termination of a for or while statement. 

8881 The auto statement (auto identifier [identifier] ...) shall cause the values of the identifiers to be 

8882 pushed down. The identifiers can be ordinary identifiers or array identifiers. Array identifiers 
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8883 shall be specified by following the array name by empty square brackets. The application shall I 

8884 ensure that the auto statement is the first statement in a function definition. I 

8885 A define statement: 

8886 define LETTER ( opt_parameter_list ) { 

8887 opt_auto_define_lis t 

8888 statement_list 

8889 } 

8890 defines a function named LETTER. If a function named LETTER was previously defined, the 

8891 define statement shall replace the previous definition. The expression: 

8892 LETTER ( opt_argument_list ) 

8893 shall invoke the function named LETTER. The behavior is undefined if the number of 

8894 arguments in the invocation does not match the number of parameters in the definition. 

8895 Functions shall be defined before they are invoked. A function shall be considered to be defined 

8896 within its own body, so recursive calls are valid. The values of numeric constants within a 

8897 function shall be interpreted in the base specified by the value of the ibase register when the 

8898 function is invoked. 

8899 The return statements (return and return (expression)) shall cause termination of a function, I 

8900 popping of its auto variables, and specification of the result of the function. The first form shall I 

8901 be equivalent to return(O). The value and scale of the result returned by the function shall be the I 

8902 value and scale of the expression returned. I 

8903 The quit statement (quit) shall stop execution of a be program at the point where the statement 

8904 occurs in the input, even if it occurs in a function definition, or in an if, for, or while statement. 

8905 The following functions shall be defined when the -1 option is specified: 

8906 s( expression ) 

8907 Sine of argument in radians. 

8908 c( expression ) 

8909 Cosine of argument in radians. 

8910 a( expression ) 

8911 Arctangent of argument. 

8912 1( expression ) 

8913 Natural logarithm of argument. 

8914 e( expression ) 

8915 Exponential function of argument. 

8916 j( expression, expression ) 

8917 Bessel function of integer order. 

8918 The scale of the result returned by these functions shall be the value of the scale register at the I 

8919 time the function is invoked. The value of the scale register after these functions have completed I 

8920 their execution shall be the same value it had upon invocation. The behavior is undefined if any I 

8921 of these functions is invoked with an argument outside the domain of the mathematical I 

8922 function. I 

8923 EXIT STATUS 

8924 The following exit values shall be returned: 

8925 0 All input files were processed successfully. 
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8926 unspecified An error occurred. 

8927 CONSEQUENCES OF ERRORS 

8928 If any file operand is specified and the named file cannot be accessed, be shall write a diagnostic 

8929 message to standard error and terminate without any further action. 

8930 In an interactive invocation of be, the utility should print an error message and recover following 

8931 any error in the input. In a non-interactive invocation of be, invalid input causes undefined 

8932 behavior. 

8933 APPLICATION USAGE 

8934 Automatic variables in be do not work in exactly the same way as in either C or PL /1 . 

8935 For historical reasons, the exit status from be cannot be relied upon to indicate that an error has 

8936 occurred. Returning zero after an error is possible. Therefore, be should be used primarily by 

8937 interactive users (who can react to error messages) or by application programs that can 

8938 somehow validate the answers returned as not including error messages. 

8939 The be utility always uses the period (' .') character to represent a radix point, regardless of any 

8940 decimal-point character specified as part of the current locale. In languages like C or aivk, the 

8941 period character is used in program source, so it can be portable and unambiguous, while the 

8942 locale-specific character is used in input and output. Because there is no distinction between 

8943 source and input in be, this arrangement would not be possible. Using the locale-specific 

8944 character in bc's input would introduce ambiguities into the language; consider the following 

8945 example in a locale with a comma as the decimal-point character: 

8946 

8947 

8948 

8949 

8950 f (1,2,3 ) 

8951 Because of such ambiguities, the period character is used in input. Having input follow different 

8952 conventions from output would be confusing in either pipeline usage or interactive usage, so the 

8953 period is also used in output. 

8954 EXAMPLES 

8955 In the shell, the following assigns an approximation of the first ten digits of ' Jt' to the variable 

8956 x: 

8957 x=$ (printf "%s\n" 'scale = 10; 104348/33215' | be) 

8958 The following be program prints the same approximation of ' 7t', with a label, to standard 

8959 output: 

8960 scale = 10 

8961 "pi equals " 

8962 1 0 4 3 4 8 / 3 3 2 1 5 

8963 The following defines a function to compute an approximate value of the exponential function 

8964 (note that such a function is predefined if the -1 option is specified): 

8965 scale = 2 0 

8966 define e (x) { 

8967 auto a, b, c, i, s 

8968 a = 1 

8969 b = 1 

8970 s = 1 


define f(a,b) { 
} 
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8971 

for (i 

= l; i == i; 

8972 

a = 

a*x 

8973 

b = 

b*i 

8974 

c = 

a/b 

8975 

if 

(c == 0) { 

8976 


return (s) 

8977 

} 


8978 

s = 

s + c 


8979 } 

8980 } 

8981 The following prints approximate values of the exponential function of the first ten integers: 

8982 for (i = 1; i <= 10; ++i) { 

8983 e (i) 

8984 } 


8985 RATIONALE 

8986 The be utility is implemented historically as a front-end processor for dc; dc was not selected to 

8987 be part of this volume of IEEE Std. 1003.1-200x because be was thought to have a more intuitive 

8988 programmatic interface. Current implementations that implement be using dc are expected to be 

8989 compliant. 

8990 The exit status for error conditions has been left unspecified for several reasons: 

8991 • The be utility is used in both interactive and non-interactive situations. Different exit codes 

8992 may be appropriate for the two uses. 


8993 • It is unclear when a non-zero exit should be given; divide-by-zero, undefined functions, and 

8994 syntax errors are all possibilities. 


8995 


• It is not clear what utility the exit status has. 


8996 

8997 

8998 


• In the 4.3 BSD, System V, and Ninth Edition implementations, be works in conjunction with 
dc. The dc utility is the parent, be is the child. This was done to cleanly terminate be if dc 
aborted. 


8999 The decision to have be exit upon encountering an inaccessible input file is based on the belief 

9000 that be filel file! is used most often when at least filel contains data/function 

9001 declarations/initializations. Having be continue with prerequisite files missing is probably not 

9002 useful. There is no implication in the CONSEQUENCES OF ERRORS section that be must check 

9003 all its files for accessibility before opening any of them. 

9004 There was considerable debate on the appropriateness of the language accepted by be. Several 

9005 reviewers preferred to see either a pure subset of the C language or some changes to make the 

9006 language more compatible with C. While the be language has some obvious similarities to C, it 

9007 has never claimed to be compatible with any version of C. An interpreter for a subset of C might 

9008 be a very worthwhile utility, and it could potentially make be obsolete. However, no such utility 

9009 is known in historical practice, and it was not within the scope of this volume of 

9010 IEEE Std. 1003.1-200x to define such a language and utility. If and when they are defined, it may 

9011 be appropriate to include them in a future version of this volume of IEEE Std. 1003.1-200x. This 

9012 left the following alternatives: 

9013 1. Exclude any calculator language from this volume of IEEE Std. 1003.1-200x. 

9014 The consensus of the standard developers was that a simple programmatic calculator 

9015 language is very useful for both applications and interactive users. The only arguments for 

9016 excluding any calculator were that it would become obsolete if and when a C-compatible 
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9017 

9018 

9019 


one emerged, or that the absence would encourage the development of such a C- 
compatible one. These arguments did not sufficiently address the needs of current 
application writers. 


9020 


2. Standardize the historical dc, possibly with minor modifications. 


9021 

9022 

9023 


The consensus of the standard developers was that dc is a fundamentally less usable 
language and that that would be far too severe a penalty for avoiding the issue of being 
similar to but incompatible with C. 


9024 


3. Standardize the historical be, possibly with minor modifications. 


9025 

9026 

9027 

9028 

9029 

9030 

9031 

9032 


This was the approach taken. Most of the proponents of changing the language would not 
have been satisfied until most or all of the incompatibilities with C were resolved. Since 
most of the changes considered most desirable would break historical applications and 
require significant modification to historical implementations, almost no modifications 
were made. The one significant modification that was made was the replacement of the 
historical be assignment operators "=+", and so on, with the more modem "+=", and so 
on. The older versions are considered to be fundamentally flawed because of the lexical 
ambiguity in uses like a=— 1. 


9033 

9034 

9035 

9036 


In order to permit implementations to deal with backwards compatibility as they see fit, 
the behavior of this one ambiguous construct was made undefined. (At least three 
implementations have been known to support this change already, so the degree of change 
involved should not be great.) 


9037 The ' %' operator is the mathematical remainder operator when scale is zero. The behavior of 

9038 this operator for other values of scale is from historical implementations of be, and has been 

9039 maintained for the sake of historical applications despite its non-intuitive nature. 


9040 Historical implementations permit setting ibase and obase to a broader range of values. This 

9041 includes values less than 2, which were not seen as sufficiently useful to standardize. These 

9042 implementations do not interpret input properly for values of ibase that are greater than 16. This 

9043 is because numeric constants are recognized syntactically, rather than lexically, as described in 

9044 this volume of IEEE Std. 1003.1-200x. They are built from lexical tokens of single hexadecimal 

9045 digits and periods. Since <blank>s between tokens are not visible at the syntactic level, it is not 

9046 possible to recognize the multi-digit "digits” used in the higher bases properly. The ability to 

9047 recognize input in these bases was not considered useful enough to require modifying these 

9048 implementations. Note that the recognition of numeric constants at the syntactic level is not a 

9049 problem with conformance to this volume of IEEE Std. 1003.1-200x, as it does not impact the 

9050 behavior of portable applications (and correct be programs). Historical implementations also 

9051 accept input with all of the digits ' 0' 9' and ' A' —' F' regardless of the value of ibase; since 

9052 digits with value greater than or equal to ibase are not really appropriate, the behavior when 

9053 they appear is undefined, except for the common case of: 


9054 ibase=8; 

9055 /* Process in octal base. */ 

9056 

9057 ibase=A 

9058 /* Restore decimal base. */ 


9059 In some historical implementations, if the expression to be written is an uninitialized array 

9060 element, a leading <space> character and/or up to four leading 0 characters may be output 

9061 before the character zero. This behavior is considered a bug; it is unlikely that any currently 

9062 portable application relies on: 


Commands and Utilities, Issue 6 


241 



be 


Utilities 


9063 echo ' b[3]' I be 

9064 returning 00000 rather than 0. 

9065 Exact calculation of the number of fractional digits to output for a given value in a base other 

9066 than 10 can be computationally expensive. Historical implementations use a faster 

9067 approximation, and this is permitted. Note that the requirements apply only to values of obase 

9068 that this volume of IEEE Std. 1003.1-200x requires implementations to support (in particular, not 

9069 to 1,0, or negative bases, if an implementation supports them as an extension). I 

9070 Historical implementations of be did not allow array parameters to be passed as the last I 

9071 parameter to a function. New implementations are encouraged to remove this restriction even I 

9072 though it is not required by the grammar. I 

9073 FUTURE DIRECTIONS 

9074 None. I 

9075 SEE ALSO 

9076 azvk 

9077 CHANGE HISTORY 

9078 First released in Issue 4. 

9079 Issue 5 

9080 FUTURE DIRECTIONS section added. I 

9081 Issue 6 I 

9082 Updated to align with the IEEE P1003.2b draft standard, which included resolution of several I 

9083 interpretations of the ISO POSIX-2:1993 standard. I 

9084 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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9085 NAME 

9086 bg — run jobs in the background 

9087 SYNOPSIS 

9088 UP bg [ job_id . . .] 

9089 

9090 DESCRIPTION 

9091 If job control is enabled (see the description of set -m), the bg utility shall resume suspended jobs 

9092 from the current environment (see Section 2.12 on page 90) by running them as background jobs. 

9093 If the job specified by job_id is already a running background job, the bg utility shall have no 

9094 effect and shall exit successfully. 

9095 Using bg to place a job into the background shall cause its process ID to become "known in the 

9096 current shell execution environment", as if it had been started as an asynchronous list; see 

9097 Section 2.9.3.1 on page 74. 

9098 OPTIONS 

9099 None. 


9100 OPERANDS 

9101 The following operand shall be supported: 


9102 

9103 

9104 

9105 


job_id Specify the job to be resumed as a background job. If no job_id operand is given, 

the most recently suspended job shall be used. The format of job_id is described in I 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.207, I 
Job Control Job ID. I 


9106 STDIN 

9107 Not used. 


9108 INPUT FILES 

9109 None. 


9110 ENVIRONMENT VARIABLES 

9111 The following environment variables shall affect the execution of bg: 


9112 

9113 

9114 

9115 

9116 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


9117 

9118 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


9119 

9120 

9121 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


9122 LC_MESSAGES 

9123 Determine the locale that should be used to affect the format and contents of 

9124 diagnostic messages written to standard error. 

9125 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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9126 ASYNCHRONOUS EVENTS 

9127 Default. 

9128 STDOUT 

9129 The output of bg shall consist of a line in the format: 

9130 "[%d] %s\n", <job~number> , <command> 

9131 where the fields are as follows: 

9132 <job-number> A number that can be used to identify the job to the wait,fg , and kill utilities. Using 

9133 these utilities, the job can be identified by prefixing the job number with ' %'. 

9134 <command> The associated command that was given to the shell. 

9135 STDERR 

9136 Used only for diagnostic messages. 

9137 OUTPUT FILES 

9138 None. 

9139 EXTENDED DESCRIPTION 

9140 None. 

9141 EXIT STATUS 

9142 The following exit values shall be returned: 

9143 0 Successful completion. 

9144 >0 An error occurred. 

9145 CONSEQUENCES OF ERRORS 

9146 If job control is disabled, the bg utility shall exit with an error and no job shall be placed in the 

9147 background. 

9148 APPLICATION USAGE 

9149 A job is generally suspended by typing the SUSP character (<control>-Z on most systems); see I 

9150 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, General Terminal I 

9151 Interface. At that point, bg can put the job into the background. This is most effective when the I 

9152 job is expecting no terminal input and its output has been redirected to non-terminal files. A 

9153 background job can be forced to stop when it has terminal output by issuing the command: 

9154 stty tostop 

9155 A background job can be stopped with the command: 

9156 kill —s stop job ID 

9157 The bg utility does not work as expected when it is operating in its own utility execution 

9158 environment because that environment has no suspended jobs. In the following examples: 

9159 ... | xargs bg 

9160 (bg) 

9161 each bg operates in a different environment and does not share its parent shell's understanding 

9162 of jobs. For this reason, bg is generally implemented as a shell regular built-in. 

9163 Application writers should note that this utility need not be provided on systems that do not 

9164 support the User Portability Utilities option. 
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9165 EXAMPLES 

9166 None. 

9167 RATIONALE 

9168 The extensions to the shell specified in this volume of IEEE Std. 1003.1-200x have mostly been 

9169 based on features provided by the KomShell. The job control features provided by bg,fg, and jobs 

9170 are also based on the KomShell. The standard developers examined the characteristics of the C 

9171 shell versions of these utilities and found that differences exist. Despite widespread use of the C 

9172 shell, the KomShell versions were selected for this volume of IEEE Std. 1003.1-200x to maintain a 

9173 degree of uniformity with the rest of the KomShell features selected (such as the very popular I 

9174 command line editing features). I 

9175 The bg utility is expected to wrap its output if the output exceeds the number of display 

9176 columns. 

9177 FUTURE DIRECTIONS 

9178 None. 

9179 SEE ALSO 

9180 fg, kill, jobs , wait 

9181 CHANGE HISTORY 

9182 First released in Issue 4. 

9183 Issue 6 

9184 This utility is now marked as part of the User Portability Utilities option. 

9185 The JC margin marker on the SYNOPSIS is removed since support for Job Control is mandatory 

9186 in this issue. This is a FIPS requirement. 
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9187 NAME 

9188 c89 — compile standard C programs 

9189 SYNOPSIS 

9190 CD c89 [— c ] [-D name[=value ]] . . . [-E] [—g] [-1 directory] . . . [-L directory] 

9191 . . . [—o outfile ] [—0] [—s] [—U name] . . . operand . . . 

9192 


9193 DESCRIPTION 

9194 The c89 utility is an interface to the standard C compilation system; it shall accept source code 

9195 conforming to the ISO C standard. The system conceptually consists of a compiler and link 

9196 editor. The files referenced by operands shall be compiled and linked to produce an executable 

9197 file. (It is unspecified whether the linking occurs entirely within the operation of c89; some 

9198 systems may produce objects that are not fully resolved until the file is executed.) 

9199 If the -c option is specified, for all path name operands of the form/z/e.c, the files: 

9200 $ (basename pathname .c).o 

9201 shall be created as the result of successful compilation. If the -c option is not specified, it is 

9202 unspecified whether such .o files are created or deleted for the file.c operands. 

9203 If there are no options that prevent link editing (such as -c or -E), and all operands compile and 

9204 link without error, the resulting executable file shall be written according to the -o outfile option 

9205 (if present) or to the file a.out. 

9206 The executable file shall be created as specified in Section 1.7.1.4 on page 11, except that the file 

9207 permission bits shall be set to: 

9208 S_IRWXO I SJRWXG I S_IRWXU 

9209 and the bits specified by the nmask of the process shall be cleared. 


9210 OPTIONS 

9211 The c89 utility shall conform to the System Interface Definitions volume of I 

9212 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that: I 

9213 • The -1 library operands have the format of options, but their position within a list of 

9214 operands affects the order in which libraries are searched. 

9215 • The order of specifying the -I and -L options is significant. 

9216 • Portable applications shall specify each option separately; that is, grouping option letters (for I 

9217 example, -cO) need not be recognized by all implementations. 

9218 The following options shall be supported: 


9219 -C 

9220 


Suppress the link-edit phase of the compilation, and do not remove any object files 
that are produced. 


9221 -g 

9222 

9223 


Produce symbolic information in the object or executable files; the nature of this 
information is unspecified, and may be modified by implementation-dependent 
interactions with other options. 


9224 -S 

9225 

9226 

9227 


Produce object or executable files, or both, from which symbolic and other 
information not required for proper execution using the exec family defined in the 
System Interfaces volume of IEEE Std. 1003.1-200x, has been removed (stripped). If 
both -g and -s options are present, the action taken is unspecified. 


9228 

9229 


-o outfile Use the path name outfile, instead of the default a.out, for the executable file 
produced. If the -o option is present with -c or -E, the result is unspecified. 
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9230 

9231 

9232 

9233 

9234 

9235 

9236 


-D name[=value ] 

Define name as if by a C-language #define directive. If no -value is given, a value of 
1 shall be used. The -D option has lower precedence than the -U option. That is, if 
name is used in both a -U and a -D option, name shall be undefined regardless of 
the order of the options. Additional implementation-dependent names may be 
provided by the compiler. Implementations shall support at least 2 048 bytes of -D 
definitions and 256 names. 


9237 

-E 

Copy C-language source 

9238 


directives; no compilation 

9239 


effects are unspecified. 


files to standard output, expanding all preprocessor 
shall be performed. If any operand is not a text file, the 


9240 

9241 

9242 

9243 

9244 

9245 

9246 

9247 

9248 


-I directory Change the algorithm for searching for headers whose names are not absolute path 
names to look in the directory named by the directory path name before looking in 
the usual places. Thus, headers whose names are enclosed in double-quotes (" ") 
shall be searched for first in the directory of the file with the #include line, then in 
directories named in -I options, and last in the usual places. For headers whose 
names are enclosed in angle brackets ("<>"), the header shall be searched for only 
in directories named in -I options and then in the usual places. Directories named 
in -I options shall be searched in the order specified. Implementations shall 
support at least ten instances of this option in a single c89 command invocation. 


9249 

9250 

9251 

9252 

9253 

9254 


-L directory Change the algorithm of searching for the libraries named in the -1 objects to look 
in the directory named by the directory path name before looking in the usual 
places. Directories named in -L options shall be searched in the order specified. 
Implementations shall support at least ten instances of this option in a single c89 
command invocation. If a directory specified by a -L option contains files named 
libc.a, libm.a, libl.a, or liby.a, the results are unspecified. 


9255 


-o 


Optimize. The nature of the optimization is unspecified. 


9256 


-U name Remove any initial definition of name. 


9257 Multiple instances of the -D, -I, -U, and -L options can be specified. 


9258 OPERANDS 

9259 An operand is either in the form of a path name or the form -1 library. The application shall 

9260 ensure that at least one operand of the path name form is specified. The following operands shall 

9261 be supported: 

9262 file. c A C-language source file to be compiled and optionally linked. The application 

9263 shall ensure that the operand is of this form if the -c option is used. 


9264 

9265 

9266 


file, a A library of object files typically produced by the ar utility, and passed directly to 

the link editor. Implementations may recognize implementation-dependent 
suffixes other than .a as denoting object file libraries. 


9267 file, o 

9268 

9269 


An object file produced by c89 -c and passed directly to the link editor. 
Implementations may recognize implementation-dependent suffixes other than .o 
as denoting object files. 


9270 The processing of other files is implementation-dependent. 


9271 -l library (The letter ell.) Search the library named: 


9272 


lib library .a 


9273 A library shall be searched when its name is encountered, so the placement of a -1 

9274 operand is significant. Several standard libraries can be specified in this manner, as 
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9275 described in the EXTENDED DESCRIPTION section. Implementations may 

9276 recognize implementation-dependent suffixes other than .a as denoting libraries. 

9277 STDIN 

9278 Not used. 


9279 INPUT FILES 

9280 The input file shall be one of the following: a text file containing a C-language source program, 

9281 an object file in the format produced by c89 -c, or a library of object files, in the format produced 

9282 by archiving zero or more object files, using ar. Implementations may supply additional utilities 

9283 that produce files in these formats. Additional input file formats are implementation-dependent. 


9284 ENVIRONMENT VARIABLES 

9285 The following environment variables shall affect the execution of c89: 


9286 

9287 

9288 

9289 

9290 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


9291 LC_ALL If set to a non-empty string value, override the values of all the other 

9292 internationalization variables. 


9293 

9294 

9295 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


9296 LC_MESSAGES 

9297 Determine the locale that should be used to affect the format and contents of 

9298 diagnostic messages written to standard error. 


9299 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

9300 TMPDIR Provide a path name that should override the default directory for temporary files, 

9301 xsi if any. On XSI-conforming systems, provide a path name that shall override the 

9302 default directory for temporary files, if any. 

9303 ASYNCHRONOUS EVENTS 

9304 Default. 


9305 STDOUT 

9306 If more than one file operand ending in .c (or possibly other unspecified suffixes) is given, for 

9307 each such file: 


9308 "%s:\n", <file> 

9309 may be written. These messages, if written, shall precede the processing of each input file; they 

9310 shall not be written to the standard output if they are written to the standard error, as described 

9311 in the STDERR section. 

9312 If the -E option is specified, the standard output shall be a text file that represents the results of 

9313 the preprocessing stage of the language; it may contain extra information appropriate for 

9314 subsequent compilation passes. 

9315 STDERR 

9316 Used only for diagnostic messages. If more than one file operand ending in .c (or possibly other 

9317 unspecified suffixes) is given, for each such file: 


248 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


c89 


9318 "%s:\n", <file> 

9319 may be written to allow identification of the diagnostic and warning messages with the 

9320 appropriate input file. These messages, if written, shall precede the processing of each input file; 

9321 they shall not be written to the standard error if they are written to the standard output, as 

9322 described in the STDOUT section. 

9323 This utility may produce warning messages about certain conditions that do not warrant 

9324 returning an error (non-zero) exit value. 

9325 OUTPUT FILES 

9326 Object files or executable files or both are produced in unspecified formats. 

9327 EXTENDED DESCRIPTION 


9328 


Standard Libraries 


9329 


The c89 utility shall recognize the following -1 operands for standard libraries: 


9330 

9331 

9332 

9333 

9334 

9335 

9336 


-1 c This operand shall make visible all library functions referenced in the System 

Interfaces volume of IEEE Std. 1003.1-200x, with the possible exception of those 
functions listed as residing in <aio.h>, <arpa/inet.h>, <math.h>, <mqueue.h>, I 
<netdb.h>, <netinet/in.h>, <pthread.h>, <sched.h>, <semaphore.h>, I 
<sys/socket.h>, pthread_atfork() in <unistd.h>, and those functions marked as an I 
RT extension in <sys/mman.h> and <time.h>. This operand shall not be required 
to be present to cause a search of this library. 


9337 

9338 


-11 


This operand shall make visible all functions required by the C-language output of 
lex that are not made available through the -1 c operand. 


9339 

9340 

9341 


-1 pthread This operand shall make visible all functions referenced in <pthread.h> and 
pthread_atfork() referenced in <unistd.h>. An implementation may search this 
library in the absence of this operand. 


9342 

9343 


-1 m This operand shall make visible all functions referenced in <math.h>. An 

implementation may search this library in the absence of this operand. 


9344 MAN 

9345 

9346 

9347 

9348 

9349 

9350 


-1 rt This operand shall make visible all functions referenced in <aio.h>, <mqueue.h>, 

<sched.h>, and <semaphore.h>, and those functions marked as an RT extension in 
<sys/mman.h> and <time.h>. An implementation may search this library in the 
absence of this operand. I 

-1 xnet This operand makes visible all functions referenced in <arpa/inet.h>, <netdb.h>, I 
<netinet/in.h>, and <sys/socket.h>. An implementation may search this library in I 
the absence of this operand. I 


9351 

9352 


-1 y This operand shall make visible all functions required by the C-language output of 

pace that are not made available through the -1 c operand. 


9353 

9354 

9355 


In the absence of options that inhibit invocation of the link editor, such as -c or -E, the c89 utility 
shall cause the equivalent of a -1 c operand to be passed to the link editor as the last -1 operand, 
causing it to be searched after all other object files and libraries are loaded. 


9356 It is unspecified whether the libraries libc.a, libm.a, librt.a, libpthread.a, libl.a, liby.a, or libxnet I 

9357 exist as regular files. The implementation may accept as -1 operands names of objects that do 

9358 not exist as regular files. 
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9359 External Symbols 

9360 The C compiler and link editor shall support the significance of external symbols up to a length 

9361 of at least 31 bytes; the action taken upon encountering symbols exceeding the implementation- 

9362 dependent maximum symbol length is unspecified. 

9363 The compiler and link editor shall support a minimum of 511 external symbols per source or 

9364 object file, and a minimum of 4095 external symbols in total. A diagnostic message shall be 

9365 written to the standard output if the implementation-dependent limit is exceeded; other actions 

9366 are unspecified. 

9367 Programming Environments 

9368 man All implementations shall support one of the following programming environments as a default. 

9369 Implementations may support more than one of the following programming environments. 

9370 Applications can use sysconf( ) or getconf to determine which programming environments are 

9371 supported. 


9372 Table 4-4 Programming Environments: Tvoe Sizes 


9373 

9374 

Programming Environment 
getconf Name 

Bits in 
int 

Bits in 
long 

Bits in 
pointer 

Bits in 
off_t 

9375 

_XBS5_ILP32_OFF32 

32 

32 

32 

32 

9376 

_XBS5_ILP32_OFFBIG 

32 

32 

32 

>64 

9377 

_XBS5_LP64_OFF64 

32 

64 

64 

64 

9378 

_XBS5_LPBIG_OFFBIG 

>32 

>64 

>64 

>64 


9379 


9380 Notes to Reviewers 

9381 This section zvith side shading zvill not appear in the final copy. - Ed. 

9382 The names of the macros above may be changed. This has been added to the issues list. 

9383 man Implementations provide configuration strings for C compiler flags, linker/loader flags, and 

9384 libraries for each supported environment. When an application needs to use a specific 

9385 programming environment rather than the implementation default programming environment 

9386 while compiling, the application shall first verify that the implementation supports the desired I 

9387 environment. If the desired programming environment is supported, the application shall then I 

9388 invoke c89 with the appropriate C compiler flags as the first options for the compile, the I 

9389 appropriate linker/loader flags after any other options but before any operands, and the 

9390 appropriate libraries at the end of the operands. 

9391 Portable applications shall not attempt to link together object files compiled for different I 

9392 programming models. Applications shall also be aware that binary data placed in shared I 

9393 memory or in files might not be recognized by applications built for other programming models. I 
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9394 

Table 4-5 Programming Environments: c89 and cc Arguments 

9395 


Programming Environment 


c89 and cc Arguments 

9396 


getconf Name 

Use 

getconf Name 

9397 


_XBS5_ILP32_OFF32 

C Compiler Flags 

XBS5_ILP32_OFF32_CFLAGS 

9398 



Linker/Loader Flags 

XBS5_ILP32_OFF32_LDFLAGS 

9399 



Libraries 

XBS5_ILP32_OFF32_LIBS 

9400 


_XBS5_ILP32_OFFBIG 

C Compiler Flags 

XBS5_ILP32_OFFBIG_CFLAGS 

9401 



Linker /Loader Flags 

XBS5_ILP32_OFFBIG_LDFLAGS 

9402 



Libraries 

XBS5_ILP32_OFFBIG_LIBS 

9403 


_XBS5_LP64_OFF64 

C Compiler Flags 

XBS5_LP64_OFF64_CFLAGS 

9404 



Linker/Loader Flags 

XBS5_LP64_OFF64_LDFLAGS 

9405 



Libraries 

XBS5_LP64_OFF64_LIBS 

9406 


_XBS5_LPBIG_OFFBIG 

C Compiler Flags 

XBS5_LPBIG_OFFBIG_CFLAGS 

9407 



Linker /Loader Flags 

XBS5_LPBIG_OFFBIG_LDFLAGS 

9408 



Libraries 

XBS5_LPBIG_OFFBIG_LIBS 


9409 


9410 Notes to Reviewers 

9411 This section with side shading will not appear in the final copy. - Ed. 

9412 The names of the macros above may be changed. This has been added to the issues list. 

9413 EXIT STATUS 

9414 The following exit values shall be returned: 

9415 0 Successful compilation or link edit. 

9416 >0 An error occurred. 

9417 CONSEQUENCES OF ERRORS 

9418 When c89 encounters a compilation error that causes an object file not to be created, it shall write 

9419 a diagnostic to standard error and continue to compile other source code operands, but it shall 

9420 not perform the link phase and return a non-zero exit status. If the link edit is unsuccessful, a 

9421 diagnostic message shall be written to standard error and c89 exits with a non-zero status. A I 

9422 portable application shall rely on the exit status of c89, rather than on the existence or mode of I 

9423 the executable file. 

9424 APPLICATION USAGE 

9425 Since the c89 utility usually creates files in the current directory during the compilation process, 

9426 it is typically necessary to run the c89 utility in a directory in which a file can be created. 

9427 On systems providing POSIX Conformance (see the System Interface Definitions volume of 

9428 IEEE Std. 1003.1-200x, Chapter 2, Conformance), c89 is required only with the the C-Language 

9429 Development option; XSI-conformant systems always provide c89. 

9430 Some historical implementations have created .o files when -c is not specified and more than 

9431 one source file is given. Since this area is left unspecified, the application cannot rely on .o files 

9432 being created, but it also must be prepared for any related .o files that already exist being deleted 

9433 at the completion of the link edit. 

9434 Some historical implementations have permitted -L options to be interspersed with -1 operands 

9435 on the command line. For an application to compile consistently on systems that do not behave 

9436 like this, it is necessary for a portable application to supply all -L options before any of the -1 

9437 options. 


Commands and Utilities, Issue 6 


251 




c89 


Utilities 


9438 

9439 

9440 

9441 

9442 

9443 


There is the possible implication that if a user supplies versions of the standard library functions 
(before they would be encountered by an implicit -1 c or explicit -1 m), that those versions 
would be used in place of the standard versions. There are various reasons this might not be 
true (functions defined as macros, manipulations for clean name space, and so on), so the 
existence of files named in the same manner as the standard libraries within the -L directories is 
explicitly stated to produce unspecified behavior. 


9444 

9445 

9446 

9447 


All of the functions specified in the System Interfaces volume of IEEE Std. 1003.1-200x may be 
made visible by implementations when the Standard C Library is searched. Portable applications 
must explicitly request searching the other standard libraries when functions made visible by 
those libraries are used. 


9448 EXAMPLES 

9449 1. 

9450 

9451 

9452 

9453 

9454 

9455 

9456 


The following usage example compiles foo.c and creates the executable file foo: 

c89 —o foo foo.c 

The following usage example compiles foo.c and creates the object file foo.o: 

c89 —c foo.c 

The following usage example compiles foo.c and creates the executable file a.out: 

c89 foo.c 

The following usage example compiles foo.c, links it with bar.o, and creates the executable 
file a.out. It also creates and leaves foo.o: 


9457 


c89 foo.c bar.o 


9458 

9459 

9460 


2. The following example shows how an application using threads interfaces can test for 
support of and use a programming environment supporting 32-bit int, long, and pointer 
types and an off_t type using at least 64 bits: 


9461 

9462 

9463 

9464 

9465 

9466 

9467 

9468 

9469 


if [ $(getconf _XBS5_ILP32_OFFBIG) != "-1" ] 
then 

c89 $(getconf XBS5_ILP32_OFFBIG_CFLAGS) -D_XOPEN_SOURCE=5 00 \ 
$(getconf XBS5_ILP32_OFFBIG_LDFLAGS) foo.c -o foo \ 

$(getconf XBS5_ILP32_OFFBIG_LIBS) -1 pthread 

else 

echo ILP32_OFFBIG programming environment not supported 
exit 1 
fi 


9470 Notes to Reviewers 

9471 This section with side shading zvill not appear in the final copy. - Ed. 

9472 The names of the macros above may be changed. This has been added to the issues list. 
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9473 

9474 

9475 

9476 

9477 

9478 

9479 

9480 

9481 

9482 

9483 

9484 

9485 

9486 

9487 

9488 

9489 

9490 

9491 

9492 

9493 

9494 

9495 

9496 

9497 

9498 

9499 

9500 

9501 

9502 

9503 

9504 

9505 

9506 

9507 

9508 

9509 

9510 

9511 

9512 

9513 

9514 

9515 

9516 

9517 

9518 


3. The following examples clarify the use and interactions of -L options and -1 operands. 

Consider the case in which module a.c calls function/() in library libQ.a, and module b.c 
calls function g() in library libp.a. Assume that both libraries reside in la/b/c. The 
command line to compile and link in the desired way is: 

c89 -L /a/b/c main.o a.c —1 Q b.c —1 p 

In this case the -1 Q operand need only precede the first -1 p operand, since both libQ.a 
and libp.a reside in the same directory. 

Multiple -L operands can be used when library name collisions occur. Building on the 
previous example, suppose that the user wants to use a new libp.a, in /a/a/a, but still wants 
/() from /a/b/c/libQ.a: 

c89 -L /a/a/a -L /a/b/c main.o a.c —1 Q b.c —1 p 

In this example, the linker searches the -L options in the order specified, and finds 
/a/a/a/libp.a before /a/b/c/libp.a when resolving references for b.c. The order of the -1 
operands is still important, however. 

RATIONALE 

The name of this utility differs from the historical cc name. The ISO/IEC 9899:1990 standard was 
approved during the original development of this volume of IEEE Std. 1003.1-200x, and it is clear 
that POSIX must support the ISO C standard; there is no other good way of specifying a C 
language. The support of the ISO C standard by c89 also mandates the ISO C standard math 
libraries. An alternative approach was considered: provide an option to select the type of 
compilation required. However, it was found that all available option letters were already in use 
in the various historical cc utilities. Thus, this name change is being used essentially as a switch. 
There was some temptation to use the name change as an excuse to mandate a cleaner interface 
(for example, to conform to the Utility Syntax Guidelines), but this was resisted; the majority of 
early c89 implementations are expected to be satisfied with historical ccs with only minimal 
changes. This was decided more from the standpoint of historical applications and makefiles 
than for the sake of the implementors. 

Note that some implementations support a more detailed model of compilation than the one 
described in the normative text. In this model, the following conceptual phases may exist: 
preprocessor, compiler, optimizer, assembler, and link editor. Such implementations may 
support these additional options to the c89 utility: 

-P Preprocess, but do not compile, the named C programs and leave the result on 

corresponding files suffixed .i. 

-S Compile the named C programs into assembly language and leave the assembler- 

language output on corresponding files suffixed .s. No object files are created. 

[-Wc,argl,arg2 ...]] 

Deliver the argument(s) argi to phase c where c is one of [p02al] indicating 
preprocessor, compiler, optimizer, assembler, or link editor, respectively. For 
example, -Wa,-m passes -m to the assembler phase. 

The -fpq options have been excluded since they use features that are not in this volume of 
IEEE Std. 1003.1-200x. In specifying that file .a operands are typically produced by ar, it is the 
intention of this volume of IEEE Std. 1003.1-200x to require that object libraries produced by ar 
be usable by c89, but not to preclude an implementation from supplying another utility that 
creates object library files. 

The -1 library operand must be capable of being interspersed with file name operands so that the 
order in which libraries are searched by the link editor can be specified. 
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9519 The search algorithm for -I directory states that the directory of the file with the #include file is 

9520 searched first, rather than being implementation-dependent. It is believed that this reflects most 

9521 implementations, and it disallows variations on different implementations, since this would 

9522 make it very difficult to distribute source code in a compatible form. 

9523 The -I options are searched in the order specified (which is left to right in English). This resolves 

9524 the conflict of which header file is used if multiple files with the same name exist in different 

9525 directories in the include path. 

9526 Notes to Reviewers 

9527 This section zvith side shading will not appear in the final copy. - Ed. 

9528 Assuming alignment with the Single UNIX Specification, then this will be mandated in this 

9529 issue. 

9530 It is unclear whether c89 requires such a large number of file descriptors that its requirement 

9531 should be documented here; this volume of IEEE Std. 1003.1-200x remains silent on the issue. It 

9532 is also noted that an undocumented feature of some C compilers is that if file descriptor 9 is 

9533 open, a linkage trace is written to it. 

9534 There is no pseudo -printf( ) specification for compile errors because no common format could be 

9535 identified. As new C compilers are written, they are encouraged to use the following format: 

9536 "%s: %s: %d %s\n", <compiler phase>, <file name>, \ 

9537 <line number> , <explanation> 

9538 The following option proposals were considered and rejected: 

9539 1. The -M option in BSD does not exist in System V and is not seen to enhance application 

9540 portability. 

9541 2. The -S option was not seen to enhance application portability and makes assumptions 

9542 about the underlying architecture. 

9543 Early proposals included a -v option to select a compiler version. Not only did this letter (and 

9544 every other uppercase and lowercase letter) conflict with one historical implementation or 

9545 another, but also there was no agreement on how many compiler versions should be defined or 

9546 what they should mean. Another choice is to specify that the cc utility invoke an ISO C standard 

9547 compiler. By specifying c89 instead, an installation is able to link either a "common usage" or an 

9548 ISO C standard compiler to the name cc. Implementors are free to select implementation- 

9549 dependent options to select (non-portable) extensions to their existing C compiler to aid the 

9550 transition to the ISO C standard. 

9551 The -g and -s options are not specified as mutually-exclusive. Historically these two options 

9552 have been mutually-exclusive, but because both are so loosely specified, it seemed cleaner to 

9553 leave their interaction unspecified. 

9554 The -E option was added because headers are not required to be separate files; these values 

9555 could be hard-coded into the compiler or might only be accessible in a non-portable way. Hence, 

9556 while not strictly required for application portability, this option is a practical necessity as a 

9557 portable means for ascertaining the real effects of preprocessor statements. 

9558 In BSD systems, using -c and -o in the same command causes the object module to be stored in 

9559 the specified file. In System V, this produces an error condition. Therefore, this volume of 

9560 IEEE Std. 1003.1-200x indicates that this is an unspecified condition. 

9561 Reasonably precise specification of standard library access is required. Implementations are not 

9562 required to have /usr/lib/libc.a, and so on, as many historical implementations do, but if they do 
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9563 not, they are required to recognize c, m, 1, and y as tokens. Libraries 1 and y can be empty if the 

9564 library functions specified for lex and yacc are accessible through the -1 operand. Historically, 

9565 these libraries have been necessary, but they are not required for a conforming implementation. 

9566 External symbol size limits are in normative text; portable applications need to know these 

9567 limits. However, the minimum maximum symbol length should be taken as a constraint on a 

9568 portable application, not on an implementation, and consequently the action taken for a symbol 

9569 exceeding the limit is unspecified. The minimum size for the external symbol table was added 

9570 for similar reasons. 

9571 The CONSEQUENCES OF ERRORS section clearly specifies the behavior of the compiler when 

9572 compilation or link-edit errors occur. The behavior of several historical implementations was 

9573 examined, and the choice was made to be silent on the status of the executable, or a.out, file in 

9574 the face of compiler or linker errors. If a linker writes the executable file, then links it on disk 

9575 with lseek( ) and write{ ) functions, the partially linked executable file can be left on disk and its 

9576 execute bits turned off if the link edit fails. However, if the linker links the image in memory 

9577 before writing the file to disk, it need not touch the executable file (if it already exists) because 

9578 the link edit fails. Since both approaches are historical practice, a portable application shall rely 

9579 on the exit status of c89, rather than on the existence or mode of the executable file. 

9580 The requirement that portable applications specify compiler options separately is to reserve the 

9581 multi-character option name space for vendor-specific compiler options, which are known to 

9582 exist in many historical implementations. Implementations are not required to recognize, for 

9583 example, -gc as if it were -g -c; nor are they forbidden from doing so. The SYNOPSIS shows all 

9584 of the options separately to highlight this requirement on applications. 

9585 Echoing file names to standard error is considered a diagnostic message because it might 

9586 otherwise be difficult to associate an error message with the erring file. The text specifies either 

9587 standard error or standard output for these messages because some historical practice uses 

9588 standard output, but there was considerable sentiment expressed for allowing it to be on 

9589 standard error instead. The rationale for using standard output is that these are not really error 

9590 message headers, but a running progress report on which files have been processed. The 

9591 messages are described as optional because there might be different ways of constructing the 

9592 messages from the compiler that should not be precluded. 

9593 FUTURE DIRECTIONS 

9594 None. 

9595 SEE ALSO 

9596 ar, getconf, make, nm, strip, umask, the System Interfaces volume of IEEE Std. 1003.1-200x, 

9597 sysconfl) 

9598 CHANGE HISTORY 

9599 First released in Issue 4. 

9600 Issue 4, Version 2 

9601 In the Standard Libraries subsection, the -1 c operand describes access to traditional interfaces if 

9602 _XOPEN_UNIX is defined. 

9603 Issue 5 

9604 In the Standard Libraries subsection, the -1 pthread and -1 rt operands are added. 

9605 A section on the use of sysconf() and getconf for determining the supported programming 

9606 environments is added. 
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9607 Issue 6 

9608 This utility is now marked as part of the C-Language Development Utilities option. 

9609 The Open Group corrigenda items U041/1 and U034/1 have been applied, correcting the 

9610 examples. 

9611 The Open Group corrigenda item U029/3 has been applied. Leading underscores were added to 

9612 the first column of Table 4-4 on page 250 and Table 4-5 on page 251. 

9613 The -1 xnet operand is added to support networking functionality. I 

9614 The following new requirements on POSIX implementations derive from alignment with the I 

9615 Single UNIX Specification: 

9616 • The -1 rt operand is added. 

9617 • The section on the use of sysconf () and getconf for determining the supported programming 

9618 environments is added. 

9619 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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9620 NAME 

9621 cal — print a calendar 

9622 SYNOPSIS 

9623 xsi cal [ [month] year ] 

9624 

9625 DESCRIPTION 


9626 Notes to Reviewers 

9627 This section zvith side shading will not appear in the final copy. - Ed. 

9628 Dl, XCU, ERN 163 notes that an action is assigned to HPA regarding cleaning up of the 

9629 wording. 

9630 The cal utility shall write a Gregorian calendar to standard output. If the year operand is 

9631 specified, a calendar for that year shall be written. If no operands are specified, a calendar for the 

9632 current month shall be written. 

9633 OPTIONS 

9634 None. 


9635 OPERANDS 

9636 The following operands shall be supported: 


9637 month 

9638 

9639 year 

9640 

9641 STDIN 

9642 Not used. 


Specify the month to be displayed, represented as a decimal integer from 1 
(January) to 12 (December). The default shall be the current month. 

Specify the year for which the calendar is displayed, represented as a decimal 
integer from 1 to 9999. The default shall be the current year. 


9643 INPUT FILES 

9644 None. 


9645 ENVIRONMENT VARIABLES 

9646 The following environment variables shall affect the execution of cal: 


9647 

9648 

9649 

9650 

9651 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


9652 LC_ALL If set to a non-empty string value, override the values of all the other 

9653 internationalization variables. 


9654 

9655 

9656 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


9657 

9658 

9659 

9660 


LCJAESSAGLS 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error, and informative messages written 
to standard output. 


9661 


LC_TIME Determine the format and contents of the calendar. 
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9662 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

9663 TZ Determine the timezone used to calculate the value of the current month. 

9664 ASYNCHRONOUS EVENTS 

9665 Default. 

9666 STDOUT 

9667 The standard output shall be used to display the calendar, in an unspecified format. 

9668 STDERR 

9669 Used only for diagnostic messages. 

9670 OUTPUT FILES 

9671 None. 

9672 EXTENDED DESCRIPTION 

9673 None. 

9674 EXIT STATUS 

9675 The following exit values shall be returned: 

9676 0 Successful completion. 

9677 >0 An error occurred. 

9678 CONSEQUENCES OF ERRORS 

9679 Default. 

9680 APPLICATION USAGE 

9681 Note that: 

9682 cal 83 

9683 refers to A.D. 83, not 1983. 

9684 EXAMPLES 

9685 None. 

9686 RATIONALE 

9687 None. 

9688 FUTURE DIRECTIONS 

9689 None. 

9690 SEE ALSO 

9691 None. 

9692 CHANGE HISTORY 

9693 First released in Issue 2. 

9694 Issue 4 

9695 Format reorganized. 

9696 Internationalized environment variable support mandated. 
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9697 NAME 

9698 cat — concatenate and print files 

9699 SYNOPSIS 

9700 cat [—u] [file . . . ] 

9701 DESCRIPTION 

9702 The cat utility reads files in sequence and writes their contents to the standard output in the 

9703 same sequence. 

9704 OPTIONS 

9705 The cat utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

9706 Section 12.2, Utility Syntax Guidelines. I 

9707 The following option shall be supported: 

9708 -u Write bytes from the input file to the standard output without delay as each is 

9709 read. 


9710 OPERANDS 

9711 The following operand shall be supported: 


9712 file 

9713 

9714 

9715 

9716 


A path name of an input file. If no file operands are specified, the standard input is 
used. If a file is ' - ', the cat utility shall read from the standard input at that point 
in the sequence. The cat utility shall not close and reopen standard input when it is 
referenced in this way, but shall accept multiple occurrences of as a file 
operand. 


9717 STDIN 

9718 The standard input is used only if no file operands are specified, or if a file operand is ' - '. See 

9719 the INPUT FILES section. 


9720 INPUT FILES 

9721 The input files can be any file type. 


9722 ENVIRONMENT VARIABLES 

9723 The following environment variables shall affect the execution of cat: 


9724 

9725 

9726 

9727 

9728 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


9729 

9730 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


9731 

9732 

9733 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


9734 LC_MESSAGES 

9735 Determine the locale that should be used to affect the format and contents of 

9736 diagnostic messages written to standard error. 

9737 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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9738 ASYNCHRONOUS EVENTS 

9739 Default. 

9740 STDOUT 

9741 The standard output shall contain the sequence of bytes read from the input files. Nothing else 

9742 shall be written to the standard output. 

9743 STDERR 

9744 Used only for diagnostic messages. 

9745 OUTPUT FILES 

9746 None. 

9747 EXTENDED DESCRIPTION 

9748 None. 

9749 EXIT STATUS 

9750 The following exit values shall be returned: 

9751 0 All input files were output successfully. 

9752 >0 An error occurred. 

9753 CONSEQUENCES OF ERRORS 

9754 Default. 

9755 APPLICATION USAGE 

9756 The -u option has value in prototyping non-blocking reads from FIFOs. The intent is to support 

9757 the following sequence: 

9758 mkfifo foo 

9759 cat -u foo > /dev/ttyl3 & 

9760 cat -u > foo 

9761 It is unspecified whether standard output is or is not buffered in the default case. This is 

9762 sometimes of interest when standard output is associated with a terminal, since buffering may 

9763 delay the output. The presence of the -u option guarantees that unbuffered I/O is available. It is 

9764 implementation-dependent whether the cat utility buffers output if the -u option is not 

9765 specified. Traditionally, the -u option is implemented using the equivalent of the setvbuf() 

9766 function defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 

9767 EXAMPLES 

9768 The following command: 

9769 cat my file 

9770 writes the contents of the file myfile to standard output. 

9771 The following command: 

9772 cat docl doc2 > doc. all 

9773 concatenates the files docl and doc2 and writes the result to doc. all. 

9774 Because of the shell language mechanism used to perform output redirection, a command such 

9775 as this: 

9776 cat doc doc. end > doc 

9777 causes the original data in doc to be lost. 

9778 The command: 
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9779 cat start — middle — end > file 

9780 when standard input is a terminal, gets two arbitrary pieces of input from the terminal with a 

9781 single invocation of cat. Note, however, that if standard input is a regular file, this would be 

9782 equivalent to the command: 

9783 cat start — middle /dev/null end > file 

9784 because the entire contents of the file would be consumed by cat the first time ' was used as a 

9785 file operand and an end-of-file condition would be detected immediately when was 

9786 referenced the second time. 

9787 RATIONALE 

9788 Historical versions of the cat utility include the options -e, -t, and -v, which permit the ends of 

9789 lines, <tab>s, and invisible characters, respectively, to be rendered visible in the output. The 

9790 standard developers omitted these options because they provide too fine a degree of control 

9791 over what is made visible, and similar output can be obtained using a command such as: 

9792 sed —n —e ' s/$/$/' — e 1 pathname 

9793 The -s option was omitted because it corresponds to different functions in BSD and System V- 

9794 based systems. The BSD -s option to squeeze blank lines can be accomplished by the shell script 

9795 shown in following example: 

9796 sed —n ' 

9797 # Write non-empty lines. 

9798 / . / { 

9799 p 

9800 d 

9801 } 

9802 # Write a single empty line, then look for more empty lines. 

9803 / ~ $ / p 

9804 # Get next line, discard the held <newline> (empty line), 

9805 # and look for more empty lines. 

9806 : Empty 

9807 /~$/ { 

9808 N 

9809 s / . / / 

9810 b Empty 

9811 } 

9812 # Write the non-empty line before going back to search 

9813 # for the first in a set of empty lines. 

9814 p 

9815 

9816 The System V -s option to silence error messages can be accomplished by redirecting the 

9817 standard error. Note that the BSD documentation for cat uses the term "blank line" to mean the 

9818 same as the POSIX "empty line": a line consisting only of a <newline>. 

9819 The BSD -n option was omitted because similar functionality can be obtained from the -n 

9820 option of the pr utility. 

9821 FUTURE DIRECTIONS 

9822 None. 
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9823 SEE ALSO 

9824 more 

9825 CHANGE HISTORY 

9826 First released in Issue 2. 

9827 Issue 4 

9828 Aligned with the ISO/IEC 9945-2:1993 standard. 
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9829 NAME 

9830 cd — change the working directory 

9831 SYNOPSIS 

9832 cd [-L] [-P] [ directory ] 

9833 man cd - 

9834 


9835 DESCRIPTION 

9836 The cd utility shall change the working directory of the current shell execution environment (see 

9837 Section 2.12 on page 90) by executing the following steps in sequence. (In the following steps, 

9838 the symbol curpath represents an intermediate value used to simplify the description of the 

9839 algorithm used by cd. There is no requirement that curpath be made visible to the application.) 


9840 

9841 

9842 


1. If no directory operand is given and the HOME environment variable is empty or 
undefined, the default behavior is implementation-dependent and no further steps shall be 
taken. 


9843 

9844 

9845 


2. If no directory operand is given and the HOME environment variable is set to a non-empty 
value, the cd utility shall behave as if the directory named in the HOME environment 
variable was specified as the directory operand. 


9846 

9847 

9848 

9849 

9850 

9851 

9852 


3. Starting with the first path name in the colon-separated path names of CDPATH (see the 
ENVIRONMENT VARIABLES section) if the path name is non-null, test if the 
concatenation of that path name, a slash character, and the operand names a directory. If 
the path name is null, test if the concatenation of dot, a slash character, and the operand 
names a directory. In either case, if the resulting string names an existing directory, set 
curpath to that string and proceed to step 4. Otherwise, repeat this step with the next path 
name in CDPATH until all path names have been tested. 


9853 

9854 

9855 

9856 

9857 

9858 

9859 

9860 

9861 

9862 


4. If the -P option is in effect, the cd utility shall perform actions equivalent to the clidir() 
function, called with curpath as the path argument. If these actions succeed, the PWD 
environment variable shall be set to an absolute path name for the current working 
directory and shall not contain file name components that, in the context of path name 
resolution, refer to a file of type symbolic link. If there is insufficient permission on the new 
directory, or on any parent of that directory, to determine the current working directory, 
the value of the PWD environment variable is unspecified. If the actions equivalent to 
chdir( ) fail for any reason, the cd utility shall display an appropriate error message and not 
alter the PWD environment variable. Whether the actions equivalent to chdir( ) succeed or 
fail, no further steps shall be taken. 


9863 5. The curpath value shall then be converted to canonical form as follows, considering each 

9864 component from beginning to end, in sequence: 


9865 

9866 


a. Dot components and any slashes that separate them from the next component shall 
be deleted. 


9867 

9868 

9869 

9870 


b. For each dot-dot component, if there is a preceding component and it is neither root 
nor dot-dot, the preceding component, all slashes separating the preceding 
component from dot-dot, dot-dot, and all slashes separating dot-dot from the 
following component shall be deleted. 


9871 

9872 

9873 

9874 

9875 


c. An implementation may further simplify curpath by removing any trailing slash 
characters that are not also leading slashes, replacing multiple non-leading 
consecutive slashes with a single slash, and replacing three or or more leading 
slashes with a single slash. If, as a result of this canonicalization, the curpath variable 
is null, no further steps shall be taken. 
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9876 6. The cd utility shall then perform actions equivalent to the chdir() function called with 

9877 curpath as the path argument. If these actions failed for any reason, the cd utility shall 

9878 display an appropriate error message and no further steps shall be taken. The PWD 

9879 environment variable shall be set to curpath. 

9880 man If, during the execution of the above steps, the PWD environment variable is changed, the 

9881 OLDPWD environment variable shall also be changed to the value of the old working directory 

9882 (that is the current working directory immediately prior to the call to cd). 

9883 OPTIONS 

9884 The cd utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

9885 Section 12.2, Utility Syntax Guidelines. 

9886 The following options shall be supported by the implementation: 

9887 -L Handle the operand dot-dot logically; symbolic link components shall not be 

9888 resolved before dot-dot components are processed (see steps 5. and 6. in the 

9889 DESCRIPTION). 

9890 -P Handle the operand dot-dot physically; symbolic link components shall be 

9891 resolved before dot-dot components are processed (see step 4. in the 

9892 DESCRIPTION). 

9893 If both -L and -P options are specified, the last of these options shall be used and all others 

9894 ignored. If neither -L nor -P is specified, the operand shall be handled dot-dot logically; see the 

9895 DESCRIPTION. 

9896 OPERANDS 

9897 The following operands shall be supported: 


directory 


9902 MAN 


STDIN 


An absolute or relative path name of the directory that shall become the new 
working directory. The interpretation of a relative path name by cd depends on the 
-L option and the CDPATH and PWD environment variables. If directory is an 
empty string, the results are unspecified. 

When a hyphen is used as the operand, this is equivalent to the command: 

cd "$OLDPWD" && pwd 

which changes to the previous working directory and then writes its name. 


Not used. 


9907 INPUT FILES 

9908 None. 

9909 ENVIRONMENT VARIABLES 

9910 The following environment variables shall affect the execution of cd: 

9911 CDPATH A colon-separated list of path names that refer to directories. The cd utility shall 

9912 use this list in its attempt to change the directory, as described in the 

9913 DESCRIPTION. An empty string in place of a directory path name represents the 

9914 current directory. If CDPATH is not set, it shall be treated as if it were an empty 

9915 string. 

9916 HOME The name of the directory, used when no directory operand is specified. 

9917 LANG Provide a default value for the internationalization variables that are unset or null. 

9918 If LANG is unset or null, the corresponding value from the implementation- 

9919 dependent default locale shall be used. If any of the internationalization variables 
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9920 

9921 


contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


9922 

9923 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


9924 

9925 

9926 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


9927 LC_MESSAGES 

9928 Determine the locale that should be used to affect the format and contents of 

9929 diagnostic messages written to standard error. 


9930 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. I 

9931 man OLDPWD A path name of the previous working directory, used by cd -. I 

9932 PWD This variable shall be set as specified in the DESCRIPTION. If an application sets I 

9933 or unsets the value of PWD, the behavior of cd is unspecified. I 


9934 ASYNCHRONOUS EVENTS 

9935 Default. 


9936 STDOUT 

9937 man If a non-empty directory name from CDPATH is used, or if cd - is used, an absolute path name of 

9938 the new working directory shall be written to the standard output as follows: 

9939 "%s\n", <new directory> 

9940 Otherwise, there shall be no output. 

9941 STDERR 

9942 Used only for diagnostic messages. 

9943 OUTPUT FILES 

9944 None. 


9945 EXTENDED DESCRIPTION 

9946 None. 


9947 EXIT STATUS 

9948 The following exit values shall be returned: 

9949 0 The directory was successfully changed. 

9950 >0 An error occurred. 


9951 CONSEQUENCES OF ERRORS 

9952 The working directory shall remain unchanged. 

9953 APPLICATION USAGE 

9954 Since cd affects the current shell execution environment, it is always provided as a shell regular 

9955 built-in. If it is called in a subshell or separate utility execution environment, such as one of the 

9956 following: 

9957 (cd /tmp) 

9958 nohup cd 

9959 find . —exec cd { } \; 

9960 it does not affect the working directory of the caller's environment. 
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9961 The user must have execute (search) permission in directory in order to change to it. 

9962 EXAMPLES 

9963 None. 

9964 RATIONALE 

9965 The use of the CDPATH was introduced in the System V shell. Its use is analogous to the use of 

9966 the PATH variable in the shell. The BSD C shell used a shell parameter cdpath for this purpose. 

9967 A common extension when HOME is undefined is to get the login directory from the user 

9968 database for the invoking user. This does not occur on System V implementations. I 

9969 Some historical shells, such as the KomShell, took special actions when the directory name I 

9970 contained a dot-dot component, selecting the logical parent of the directory, rather than the I 

9971 actual parent directory; that is, it moved up one level toward the ' /' in the path name, I 

9972 remembering what the user typed, rather than performing the equivalent of: I 

9973 chdir I 

9974 In such a shell, the following commands would not necessarily produce equivalent output for all I 

9975 directories: I 

9976 cd .. && Is Is.. I 

9977 This behavior is not permitted by default because it is not consistent with the definition of dot- I 

9978 dot in most historical practice; that is, while this behavior has been optionally available in the I 

9979 KornShell, other shells have historically not supported this functionality. The logical path name I 

9980 is stored in the PWD environment variable when the cd utility completes and this value is used I 

9981 to construct the next directory name if cd is invoked with the -L option. I 

9982 FUTURE DIRECTIONS 

9983 None. 

9984 SEE ALSO 

9985 pzvd, the System Interfaces volume of IEEE Std. 1003.1-200x, chdir( ) 

9986 CHANGE HISTORY 

9987 First released in Issue 2. 

9988 Issue 4 

9989 Aligned with the ISO/IEC 9945-2:1993 standard. 

9990 Extensions added for cd -, PWD , and OLDPWD. 

9991 Issue 6 

9992 The following new requirements on POSIX implementations derive from alignment with the 

9993 Single UNIX Specification: 

9994 • The cd -, PWD , and OLDPWD are added. 

9995 The -L and -P options are added to align with the IEEE P1003.2b draft standard. This also I 

9996 includes the introduction of a new description to include the effect of these options. I 
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9997 NAME 

9998 cflow — generate a C-language flowgraph (DEVELOPMENT) 

9999 SYNOPSIS 


10000 XSI 

cflow [-r][-d 

num ] [—D name[ = def] ] . . 

. . [—i incl ] [—1 dir] . . . 

10001 

[—U dir] 

. . . file . . . 



10002 

10003 DESCRIPTION 

10004 The cflozv utility shall analyse a collection of object files or assembler, C-language, lex or yacc 

10005 source files, and attempt to build a graph, written to standard output, charting the external 

10006 references. 


10007 OPTIONS 

10008 The cflozv utility shall conform to the System Interface Definitions volume of I 

10009 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that the order of the -D, —I, I 

10010 and -U options (which are identical to their interpretation by c89) is significant. 

10011 The following options shall be supported: 


10012 

10013 

10014 

10015 


-d num Indicate the depth at which the flowgraph is cut off. The application shall ensure I 
that the argument man is a decimal integer. By default this is a very large number I 
(typically greater than 32 000). Attempts to set the cut-off depth to a non-positive 
integer are ignored. 


10016 -i incl Increase the number of included symbols. The incl option-argument is one of the 

10017 following characters: 


10018 

10019 


x Include external and static data symbols. The default shall be to include only 
functions in the flowgraph. 


10020 

10021 


(Underscore) Include names that begin with an underscore. The default shall 
be to exclude these functions (and data if -i x is used). 


10022 -r Reverse the callercallee relationship, producing an inverted listing showing the 

10023 callers of each function. The listing is also sorted in lexicographical order by callee. 


10024 OPERANDS 

10025 The following operand is supported: 


The path name of a file for which a graph is to be generated. Files suffixed in .1, .y, 
.c, and .i shall be processed by lex and yacc and preprocessed by the c89 
preprocessor phase (bypassed for .i files) as appropriate, and then run through the 
first pass of lint. Files suffixed with .s shall be assembled and information shall be 
extracted (as in .o files) from the symbol table. 

10031 STDIN 

10032 Not used. 


10026 file 

10027 

10028 

10029 

10030 


10033 INPUT FILES 

10034 The input files shall be object files or assembler, C-language, lex or yacc source files. 

10035 ENVIRONMENT VARIABLES 

10036 The following environment variables shall affect the execution of cflozv: 

10037 LANG Provide a default value for the internationalization variables that are unset or null. 

10038 If LANG is unset or null, the corresponding value from the implementation- 

10039 dependent default locale shall be used. If any of the internationalization variables 

10040 contains an invalid setting, the utility shall behave as if none of the variables had 

10041 been defined. 
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10042 

10043 

10044 

10045 

10046 

10047 

10048 

10049 

10050 

10051 

10052 

10053 

10054 

10055 

10056 

10057 

10058 

10059 

10060 
10061 
10062 

10063 

10064 

10065 

10066 

10067 

10068 

10069 

10070 

10071 

10072 

10073 

10074 

10075 

10076 

10077 

10078 

10079 

10080 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the ordering of the output when the -r option is used. 

LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LCJAESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The flowgraph written to standard output shall be formatted as follows: 

"%d %s:%s\n", <reference number>, <global>, <definition> 

Each line of output begins with a reference (that is, line) number, followed by indentation of at 
least one column position per level. This is followed by the name of the global, a colon, and its 
definition. Normally globals are only functions not defined as an external or beginning with an 
underscore; see the OPTIONS section for the -i inclusion option. For information extracted from 
C-language source, the definition consists of an abstract type declaration (for example, char*) 
and, delimited by angle brackets, the name of the source file and the line number where the 
definition was found. Definitions extracted from object files indicate the file name and location 
counter under which the symbol appeared (for example, text). 

Once a definition of a name has been written, subsequent references to that name contain only 
the reference number of the line where the definition can be found. For undefined references, 
only " < > " shall be written. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 
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10081 APPLICATION USAGE 

10082 Files produced by lex and yacc cause the reordering of line number declarations, and this can 

10083 confuse cflow. To obtain proper results, the input of yacc or lex must be directed to cflow. 

10084 EXAMPLES 

10085 Given the following in file.c: 

10086 int i; 

10087 main () 

10088 { 

10089 f () ; 

10090 g () ; 

10091 f () ; 

10092 } 

10093 f () 

10094 { 

10095 i = h () ; 

10096 } 

10097 The command: 

10098 cflow —i x file.c 

10099 produces the output: 

10100 1 main: int(), <file.c 2> 

10101 2 f: int(), <file.c 8> 

10102 3 h: <> 

10103 4 i: int, <file.c 1> 

10104 5 g: <> 

10105 RATIONALE 

10106 None. 

10107 FUTURE DIRECTIONS 

10108 None. 

10109 SEE ALSO 

10110 c89, lex, yacc 

10111 CHANGE HISTORY 

10112 First released in Issue 2. 

10113 Issue 4 

10114 Format reorganized. 

10115 Internationalized environment variable support mandated. 

10116 Issue 6 

10117 The normative text is reworded to avoid use of the term "must” for application requirements. 
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10118 NAME 

10119 chgrp — change the file group ownership 

10120 SYNOPSIS 

10121 chgrp —hR group file . . . 

10122 chgrp —R [—H | —L | —P ] group file . . . 

10123 DESCRIPTION 

10124 The chgrp utility shall set the group ID of the file named by each file operand to the group ID 

10125 specified by the group operand. 

10126 For each file operand, it shall perform actions equivalent to the chozvn() function defined in the 

10127 System Interfaces volume of IEEE Std. 1003.1-200x, called with the following arguments: 

10128 • The file operand shall be used as the path argument. 

10129 • The user ID of the file shall be used as the owner argument. 

10130 • The specified group ID shall be used as the group argument. 

10131 Unless chgrp is invoked by a process with appropriate privileges, the set-user-ID and set-group- 

10132 ID bits of a regular file shall be cleared upon successful completion; the set-user-ID and set- 

10133 group-ID bits of other file types may be cleared. 


10134 OPTIONS 

10135 The chgrp utility shall conform to the System Interface Definitions volume of 

10136 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

10137 The following options shall be supported by the implementation: 


10138 -h 

10139 

10140 

10141 

10142 

10143 


If the system supports group IDs for symbolic links, for each file operand that 
names a file of type symbolic link, chgrp shall attempt to set the group ID of the 
symbolic link instead of the file referenced by the symbolic link. If the system does 
not support group IDs for symbolic links, for each file operand that names a file of 
type symbolic link, chgrp shall do nothing more with the current file and shall go 
on to any remaining files. 


10144 -H 

10145 

10146 


If the -R option is specified and a symbolic link referencing a file of type directory 
is specified on the command line, chgrp shall change the group of the directory 
referenced by the symbolic link and all files in the file hierarchy below it. 


10147 -L 

10148 

10149 

10150 


If the -R option is specified and a symbolic link referencing a file of type directory 
is specified on the command line or encountered during the traversal of a file 
hierarchy, chgrp shall change the group of the directory referenced by the symbolic 
link and all files in the file hierarchy below it. 


10151 -P 

10152 

10153 

10154 


If the -R option is specified and a symbolic link is specified on the command line 
or encountered during the traversal of a file hierarchy, chgrp shall change the 
group ID of the symbolic link if the system supports this operation. The chgrp 
utility shall not follow the symbolic link to any other part of the file hierarchy. 


10155 -R 

10156 

10157 

10158 


Recursively change file group IDs. For each file operand that names a directory, 
chgrp shall change the group of the directory and all files in the file hierarchy below 
it. Unless a -H, -L, or -P option is specified, it is unspecified which of these 
options will be used as the default. 


10159 Specifying more than one of the mutually-exclusive options -H, -L, and -P shall not be 

10160 considered an error. The last option specified shall determine the behavior of the utility. 


270 


Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


chgrp 


10161 

10162 

10163 

10164 

10165 

10166 

10167 

10168 

10169 

10170 

10171 

10172 

10173 

10174 

10175 

10176 

10177 

10178 

10179 

10180 

10181 

10182 

10183 

10184 

10185 

10186 

10187 

10188 

10189 

10190 

10191 

10192 

10193 

10194 

10195 

10196 

10197 

10198 

10199 

10200 
10201 


OPERANDS 

The following operands shall be supported: 

group A group name from the group database or a numeric group ID. Either specifies a 

group ID to be given to each file named by one of the file operands. If a numeric 
group operand exists in the group database as a group name, the group ID number 
associated with that group name is used as the group ID. 

file A path name of a file whose group ID is to be modified. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of chgrp: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 

Default. 

STDOUT 

Not used. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The utility executed successfully and all requested changes were made. 

>0 An error occurred. 
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10202 

10203 

10204 

10205 

10206 

10207 

10208 

10209 

10210 
10211 
10212 

10213 

10214 

10215 

10216 

10217 

10218 

10219 

10220 
10221 
10222 

10223 

10224 

10225 

10226 

10227 

10228 

10229 

10230 

10231 

10232 

10233 


CONSEQUENCES OF ERRORS 

If, when invoked with the -R option, chgrp attempts but fails to change the group ID of a 
particular file in a specified file hierarchy, it shall continue to process the remaining files in the 
hierarchy. If chgrp cannot read or search a directory within a hierarchy, it shall continue to 
process the other parts of the hierarchy that are accessible. 

APPLICATION USAGE 

Only the owner of a file or the user with appropriate privileges may change the owner or group 
of a file. 

Some systems restrict the use of chgrp to a user with appropriate privileges when the group 
specified is not the effective group ID or one of the supplementary group IDs of the calling 
process. 

EXAMPLES 

None. 

RATIONALE 

The System V and BSD versions use different exit status codes. Some implementations used the 
exit status as a count of the number of errors that occurred; this practice is unworkable since it 
can overflow the range of valid exit status values. The standard developers chose to mask these 
by specifying only 0 and >0 as exit values. 

The functionality of chgrp is described substantially through references to chozvn(). In this way, 
there is no duplication of effort required for describing the interactions of permissions, multiple 
groups, and so on. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

chmod, chown , the System Interfaces volume of IEEE Std. 1003.1-200x, chozvn () 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. I 

Issue 6 I 

New options -H, -L, and -P are added to align with the IEEE P1003.2b draft standard. These I 
options affect the processing of symbolic links. I 
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10234 NAME 

10235 chmod — change the file modes 

10236 SYNOPSIS 

10237 chmod [— R] mode file . . . 

10238 DESCRIPTION 

10239 The chmod utility shall change any or all of the file mode bits of the file named by each file 

10240 operand in the way specified by the mode operand. 

10241 It is implementation-dependent whether and how the chmod utility affects any alternate or 

10242 additional file access control mechanism (see the System Interface Definitions volume of I 

10243 IEEE Std. 1003.1-200x, Section 4.1, File Access Permissions) being used for the specified file. I 

10244 Only a process whose effective user ID matches the user ID of the file, or a process with the 

10245 appropriate privileges, shall be permitted to change the file mode bits of a file. 

10246 OPTIONS 

10247 The chmod utility shall conform to the System Interface Definitions volume of I 

10248 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

10249 The following option shall be supported: 


10250 

-R 

Recursively change file mode bits. For each file operand that names a directory. 

10251 


chmod shall change the file mode bits of the directory and all files in the file 

10252 


hierarchy below it. 

10253 OPERANDS 


10254 

The following operands shall be supported: 

10255 

mode 

Represents the change to be made to the file mode bits of each file named by one of 

10256 


the file operands; see the EXTENDED DESCRIPTION section. 

10257 

file 

A path name of a file whose file mode bits shall be modified. 

10258 STDIN 



10259 

Not used. 


10260 INPUT FILES 


10261 

None. 


10262 ENVIRONMENT VARIABLES 

10263 

The following environment variables shall affect the execution of chmod: 

10264 

LANG 

Provide a default value for the internationalization variables that are unset or null. 

10265 


If LANG is unset or null, the corresponding value from the implementation- 

10266 


dependent default locale shall be used. If any of the internationalization variables 

10267 


contains an invalid setting, the utility shall behave as if none of the variables had 

10268 


been defined. 

10269 

LC_ALL 

If set to a non-empty string value, override the values of all the other 

10270 


internationalization variables. 

10271 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 

10272 


characters (for example, single-byte as opposed to multi-byte characters in 

10273 


arguments). 

10274 

LC_MESSAGES 

10275 


Determine the locale that should be used to affect the format and contents of 

10276 


diagnostic messages written to standard error. 
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10277 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

10278 ASYNCHRONOUS EVENTS 

10279 Default. 

10280 STDOUT 

10281 Not used. 

10282 STDERR 

10283 Used only for diagnostic messages. 

10284 OUTPUT FILES 

10285 None. 

10286 EXTENDED DESCRIPTION 

10287 man The mode operand shall be either a symbolic_mode expression or a non-negative octal integer. The 

10288 symbolicjnode form is described by the grammar later in this section. 

10289 Notes to Reviewers 

10290 Tins section with side shading will not appear in the final copy. - Ed. 

10291 Please check that the following sentence should have "clause” in a special font. 

10292 Each clause shall specify an operation to be performed on the current file mode bits of each file. 

10293 The operations shall be performed on each file in the order in which the clauses are specified. 

10294 The zvho symbols u, g, and o shall specify the user, group, and other parts of the file mode bits, 

10295 respectively. A zvho consisting of the symbol a shall be equivalent to ugo. 

10296 The perm symbols r, zv, and x represent the read, zvrite, and execute/search portions of file mode 

10297 bits, respectively. The perm symbol s shall represent the set-user-ID-on-execution (when who 

10298 contains or implies u) and set-group-ID-on-execution (when who contains or implies g) bits. 

10299 The perm symbol X shall represent the execute /search portion of the file mode bits if the file is a 

10300 directory or if the current (unmodified) file mode bits have at least one of the execute bits 

10301 (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is not a directory and none of 

10302 the execute bits are set in the current file mode bits. 

10303 The permcopy symbols u, g, and o shall represent the current permissions associated with the 

10304 user, group, and other parts of the file mode bits, respectively. For the remainder of this section, 

10305 perm refers to the non-terminals perm and permcopy in the grammar. 

10306 If multiple actionlists are grouped with a single wholist in the grammar, each actionlist shall be 

10307 applied in the order specified with that wholist. The op symbols shall represent the operation 

10308 performed, as follows: 

10309 + If perm is not specified, the ' +' operation shall not change the file mode bits. 

10310 If who is not specified, the file mode bits represented by perm for the owner, group, and 

10311 other permissions, except for those with corresponding bits in the file mode creation mask 

10312 of the invoking process, shall be set. 

10313 Otherwise, the file mode bits represented by the specified who and perm values shall be set. 

10314 - If perm is not specified, the ' —' operation shall not change the file mode bits. 

10315 If who is not specified, the file mode bits represented by perm for the owner, group, and 

10316 other permissions, except for those with corresponding bits in the file mode creation mask 

10317 of the invoking process, shall be cleared. 


274 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


chmod 


10318 

10319 

10320 

10321 

10322 

10323 

10324 

10325 

10326 

10327 

10328 

10329 

10330 

10331 

10332 

10333 

10334 

10335 

10336 

10337 

10338 

10339 

10340 

10341 

10342 

10343 

10344 

10345 MAN 

10346 

10347 

10348 

10349 

10350 

10351 

10352 

10353 

10354 

10355 

10356 

10357 

10358 


Otherwise, the file mode bits represented by the specified who and perm values shall be 
cleared. 

= Clear the file mode bits specified by the who value, or, if no who value is specified, all of the 
file mode bits specified in this volume of IEEE Std. 1003.1-200x. 

If perm is not specified, the ' =' operation shall make no further modifications to the file 
mode bits. 

If who is not specified, the file mode bits represented by perm for the owner, group, and 
other permissions, except for those with corresponding bits in the file mode creation mask 
of the invoking process, shall be set. 

Otherwise, the file mode bits represented by the specified who and perm values shall be set. 

When using the symbolic mode form on a regular file, it is implementation-dependent whether 
or not: 

• Requests to set the set-user-ID-on-execution or set-group-ID-on-execution bit when all 
execute bits are currently clear and none are being set are ignored. 

• Requests to clear all execute bits also clear the set-user-ID-on-execution and set-group-ID- 
on-execution bits. 

• Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution bits when all 
execute bits are currently clear are ignored. However, if the command Is -l file writes an s in 
the position indicating that the set-user-ID-on-execution or set-group-ID-on-execution is set, 
the commands chmod u-s file or chmod g-s file, respectively, shall not be ignored. 

When using the symbolic mode form on other file types, it is implementation-dependent 
whether or not requests to set or clear the set-user-ID-on-execution or set-group-ID-on- 
execution bits are honored. 

If the who symbol o is used in conjunction with the perm symbol s with no other who symbols 
being specified, the set-user-ID-on-execution and set-group-ID-on-execution bits shall not be 
modified. It shall not be an error to specify the who symbol o in conjunction with the perm 
symbol s. 

For an octal integer mode operand, the file mode bits shall be set absolutely. 

For each bit set in the octal number, the corresponding file permission bit shown in the following 
table shall be set; all other file permission bits shall be cleared. For regular files, for each bit set in 
the octal number corresponding to the set-user-ID-on-execution or the set-group-ID-on- 
execution, bits shown in the following table shall be set; if these bits are not set in the octal 
number, they are cleared. For other file types, it is implementation-dependent whether or not 
requests to set or clear the set-user-ID-on-execution or set-group-ID-on-execution bits are 
honored. 



Octal Mode Bit 

Octal Mode Bit 

Octal Mode Bit 

Octal Mode Bit 



4000 SJSUID 

0400 S_IRUSR 

0040 S_IRGRP 

0004 S_IROTH 



2000 S_ISGID 

0200 S_IWUSR 

0020 S_IWGRP 

0002 S_IWOTH 




0100 S_IXUSR 

0010 S_IXGRP 

0001 S_IXOTH 



When bits are set in the octal number other than those listed in the table above, the behavior is 
unspecified. 
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10359 

10360 

10361 

10362 

10363 

10364 

10365 

10366 

10367 

10368 

10369 

10370 

10371 

10372 

10373 

10374 

10375 

10376 

10377 

10378 

10379 

10380 

10381 

10382 

10383 

10384 

10385 

10386 

10387 

10388 

10389 

10390 

10391 

10392 

10393 

10394 

10395 

10396 

10397 

10398 


Grammar for chmod 

The grammar and lexical conventions in this section describe the syntax for the symbolic,jnode 
operand. The general conventions for this style of grammar are described in Section 1.10 on page 
24. A valid symbolic_mode can be represented as the non-terminal symbol symbolic_mode in the 
grammar. This formal syntax shall take precedence over the preceding text syntax description. 

The lexical processing is based entirely on single characters. Implementations need not allow 
blank characters within the single argument being processed. 


%start symbolic_mode 

"6 "5 

symbolic_mode 

: section 

1 symbolic_mode ',' section 

section 

: actionlist 
| wholist actionlist 

wholist 

: who 

| wholist who 

who 

: 'u' 1 'g' 1 'o' | 'a' 

actionlist 

: action 

I actionlist action 

action 

: op 

I op permlist 

I op permcopy 

r 

permcopy 

: 'u' I ’ q’ | 'o' 

r 

op 

r 

permlist 

: perm 

| perm permlist 

r 

perm 

: 'r' I 'w' | 'x' | 'X' | 's' 


EXIT STATUS 

The following exit values shall be returned: 

0 The utility executed successfully and all requested changes were made. 
>0 An error occurred. 
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10399 

10400 

10401 

10402 

10403 

10404 

10405 

10406 

10407 

10408 

10409 

10410 

10411 

10412 

10413 

10414 

10415 

10416 

10417 

10418 

10419 

10420 

10421 

10422 

10423 

10424 

10425 

10426 

10427 

10428 

10429 

10430 

10431 

10432 

10433 

10434 

10435 

10436 

10437 

10438 

10439 

10440 

10441 

10442 

10443 

10444 


CONSEQUENCES OF ERRORS 

If, when invoked with the -R option, chmod attempts but fails to change the mode of a particular 
file in a specified file hierarchy, it shall continue to process the remaining files in the hierarchy, 
affecting the final exit status. If chmod cannot read or search a directory within a hierarchy, it 
shall continue to process the other parts of the hierarchy that are accessible. 

APPLICATION USAGE 

Some implementations of the chmod utility change the mode of a directory before the files in the 
directory when performing a recursive (-R option) change; others change the directory mode 
after the files in the directory. If an application tries to remove read or search permission for a 
file hierarchy, the removal attempt fails if the directory is changed first; on the other hand, trying 
to re-enable permissions to a restricted hierarchy fails if directories are changed last. Users 
should not try to make a hierarchy inaccessible to themselves. 

Some implementations of chmod never used the process' umask when changing modes; systems 
conformant with this volume of IEEE Std. 1003.1-200x do so when who is not specified. Note the 
difference between: 

chmod a—w file 

which removes all write permissions, and: 

chmod — —w file 

which removes write permissions that would be allowed if file was created with the same 
umask. 

Portable applications should never assume that they know how the set-user-ID and set-group- 
ID bits on directories are interpreted. 

EXAMPLES 


Mode 

Results 

a+- 

Equivalent to a+,a=', clears all file mode bits. 

go- 1—w 

Equivalent to go+,go-iv; clears group and other 
write bits. 

g=o-w 

Equivalent to g=o,g-w; sets group bit to match 
other bits and then clears group write bit. 

g-r+iv 

Equivalent to g-r,g+w; clears group read bit and 
sets group write bit. 

=S 

Sets owner bits to match group bits and sets 
other bits to match group bits. 


RATIONALE 

The functionality of chmod is described substantially through references to concepts defined in 
the System Interfaces volume of IEEE Std. 1003.1-200x. In this way, there is less duplication of 
effort required for describing the interactions of permissions, and so on. However, the behavior 
of this utility is not described in terms of the chmod () function from the System Interfaces 
volume of IEEE Std. 1003.1-200x because that specification requires certain side effects upon 
alternate file access control mechanisms that might not be appropriate, depending on the 
implementation. 

Implementations that support mandatory file and record locking as specified by the 1984 
/usr/group standard historically used the combination of set-group-ID bit set and group 
execute bit clear to indicate mandatory locking. This condition is usually set or cleared with the 
symbolic mode perm symbol 1 instead of the perm symbols s and x so that the mandatory locking 
mode is not changed without explicit indication that that was what the user intended. Therefore, 
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10445 

10446 

10447 

10448 

10449 

10450 

10451 

10452 

10453 

10454 

10455 

10456 

10457 

10458 

10459 

10460 

10461 

10462 

10463 

10464 

10465 

10466 

10467 

10468 

10469 

10470 

10471 

10472 

10473 

10474 

10475 

10476 

10477 

10478 

10479 

10480 

10481 

10482 


the details on how the implementation treats these conditions must be defined in the 
documentation. This volume of IEEE Std. 1003.1-200x does not require mandatory locking (nor 
does the System Interfaces volume of IEEE Std. 1003.1-200x), but does allow it as an extension. 
However, this volume of IEEE Std. 1003.1-200x does require that the Is and chmod utilities work 
consistently in this area. If Is -l file indicates that the set-group-ID bit is set, chmod g-s file must 
clear it (assuming appropriate privileges exist to change modes). 

The System V and BSD versions use different exit status codes. Some implementations used the 
exit status as a count of the number of errors that occurred; this practice is unworkable since it 
can overflow the range of valid exit status values. This problem is avoided here by specifying 
only 0 and >0 as exit values. 

The System Interfaces volume of IEEE Std. 1003.1-200x indicates that implementation-dependent 
restrictions may cause the S_ISUID and S_ISGID bits to be ignored. This volume of 
IEEE Std. 1003.1-200x allows the chmod utility to choose to modify these bits before calling 
chmod () (or some function providing equivalent capabilities) for non-regular files. Among other 
things, this allows implementations that use the set-user-ID and set-group-ID bits on directories 
to enable extended features to handle these extensions in an intelligent manner. 

The X perm symbol was adopted from BSD-based systems because it provides commonly 
desired functionality when doing recursive (-R option) modifications. Similar functionality is 
not provided by th e find utility. Historical BSD versions of chmod, however, only supported X 
with op+ ; it has been extended in this volume of IEEE Std. 1003.1-200x because it is also useful 
with op-. (It has also been added for op- even though it duplicates x, in this case, because it is 
intuitive and easier to explain.) 

The grammar was extended with the permcopy non-terminal to allow historical-practice forms of 
symbolic modes like o=u -g (that is, set the "other" permissions to the permissions of "owner" 
minus the permissions of "group"). 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Is, nmask, the System Interfaces volume of IEEE Std. 1003.1-200x, chmod() 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• Octal modes have been kept and made mandatory despite being marked obsolescent in the 
previous version of this volume of IEEE Std. 1003.1-200x. 
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10483 

10484 

10485 

10486 

10487 

10488 

10489 

10490 

10491 

10492 

10493 

10494 

10495 

10496 

10497 

10498 

10499 

10500 

10501 

10502 

10503 

10504 

10505 

10506 

10507 

10508 

10509 

10510 

10511 

10512 

10513 

10514 

10515 

10516 

10517 

10518 

10519 

10520 

10521 

10522 

10523 

10524 

10525 

10526 


NAME 

chown — change the file ownership 

SYNOPSIS 

chown —hR owner[:group] file ... 

chown —R [—H | —L | —P ] owner [: group] file ... 

DESCRIPTION 

The chozvn utility shall set the user ID of the file named by each file operand to the user ID 
specified by the owner operand. 

For each file operand, it shall perform actions equivalent to the chozvn () function defined in the 
System Interfaces volume of IEEE Std. 1003.1-200x, called with the following arguments: 

1. The file operand shall be used as the path argument. 

2. The user ID indicated by the ozvner portion of the first operand shall be used as the ozvner 
argument. 

3. If the group portion of the first operand is given, the group ID indicated by it shall be used 
as the group argument; otherwise, the group ID of the file shall be used as the group 
argument. 

Unless chozvn is invoked by a process with appropriate privileges, the set-user-ID and set- 
group-ID bits of a regular file shall be cleared upon successful completion; the set-user-ID and 
set-group-ID bits of other file types may be cleared. 

OPTIONS 

The chozvn utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported by the implementation: 

-h If the system supports user IDs for symbolic links, for each file operand that names 

a file of type symbolic link, chozvn shall attempt to set the user ID of the symbolic 
link. If the system supports group IDs for symbolic links, and a group ID was 
specified, for each file operand that names a file of type symbolic link, chozvn shall 
attempt to set the group ID of the symbolic link. If the system does not support 
user or group IDs for symbolic links, for each file operand that names a file of type 
symbolic link, chozvn shall do nothing more with the current file and shall go on to 
any remaining files. 

-H If the -R option is specified and a symbolic link referencing a file of type directory 

is specified on the command line, chozvn shall change the user ID (and group ID, if 
specified) of the directory referenced by the symbolic link and all files in the file 
hierarchy below it. 

-L If the -R option is specified and a symbolic link referencing a file of type directory 

is specified on the command line or encountered during the traversal of a file 
hierarchy, chozvn shall change the user ID (and group ID, if specified) of the 
directory referenced by the symbolic link and all files in the file hierarchy below it. 

-P If the -R option is specified and a symbolic link is specified on the command line 

or encountered during the traversal of a file hierarchy, chozvn shall change the 
owner ID (and group ID, if specified) of the symbolic link if the system supports 
this operation. The chozvn utility shall not follow the symbolic link to any other 
part of the file hierarchy. 
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10527 -R Recursively change file user and group IDs. For each file operand that names a I 

10528 directory, chown shall change the user ID (and group ID, if specified) of the I 

10529 directory and all files in the file hierarchy below it. Unless a -H, -L, or -P option is I 

10530 specified, it is unspecified which of these options will be used as the default. I 

10531 Specifying more than one of the mutually-exclusive options -H, -L, and -P shall not be I 

10532 considered an error. The last option specified shall determine the behavior of the utility. I 


10533 OPERANDS 

10534 The following operands shall be supported: 


10535 

10536 

10537 

10538 

10539 

10540 

10541 

10542 

10543 

10544 


owner[:group] A user ID and optional group ID to be assigned to file. The application shall I 
ensure that the owner portion of this operand is a user name from the user database I 
or a numeric user ID. Either specifies a user ID to be given to each file named by I 
one of the file operands. If a numeric owner operand exists in the user database as a 
user name, the user ID number associated with that user name is used as the user 
ID. Similarly, if the group portion of this operand is present, it shall be a group I 
name from the group database or a numeric group ID. Either specifies a group ID I 
to be given to each file. If a numeric group operand exists in the group database as 
a group name, the group ID number associated with that group name shall be used 
as the group ID. 


10545 file 


A path name of a file whose user ID is to be modified. 


10546 STDIN 

10547 Not used. 


10548 INPUT FILES 

10549 None. 


10550 ENVIRONMENT VARIABLES 


10551 

The following environment variables shall affect the execution of chown: 

10552 

10553 

10554 

10555 

10556 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

10557 

10558 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

10559 

10560 

10561 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

10562 

10563 

10564 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

10565 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


10566 ASYNCHRONOUS EVENTS 

10567 Default. 


10568 STDOUT 

10569 Not used. 
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10570 

10571 

10572 

10573 

10574 

10575 

10576 

10577 

10578 

10579 

10580 

10581 

10582 

10583 

10584 

10585 

10586 

10587 

10588 

10589 

10590 

10591 

10592 

10593 

10594 

10595 

10596 

10597 

10598 

10599 

10600 
10601 

10602 

10603 

10604 

10605 

10606 

10607 

10608 

10609 

10610 
10611 
10612 
10613 


STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The utility executed successfully and all requested changes were made. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If, when invoked with the -R option, chown attempts but fails to change the user ID or, if the 
group operand is specified, group ID, of a particular file in a specified file hierarchy, it shall 
continue to process the remaining files in the hierarchy. 

If chown cannot read or search a directory within a hierarchy, it shall continue to process the 
other parts of the hierarchy that are accessible. 

APPLICATION USAGE 

Only the owner of a file or the user with appropriate privileges may change the owner or group 
of a file. 

Some systems restrict the use of chown to a user with appropriate privileges. 

EXAMPLES 

None. 

RATIONALE 

The System V and BSD versions use different exit status codes. Some implementations used the 
exit status as a count of the number of errors that occurred; this practice is unworkable since it 
can overflow the range of valid exit status values. These are masked by specifying only 0 and >0 
as exit values. 

The functionality of chown is described substantially through references to functions in the 
System Interfaces volume of IEEE Std. 1003.1-200x. In this way, there is no duplication of effort 
required for describing the interactions of permissions, multiple groups, and so on. 

The 4.3 BSD method of specifying both owner and group was included in this volume of 
IEEE Std. 1003.1-200x because: 

• There are cases where the desired end condition could not be achieved using the chgrp and 
chown (that only changed the user ID) utilities. (If the current owner is not a member of the 
desired group and the desired owner is not a member of the current group, the choivn() 
function could fail unless both owner and group are changed at the same time.) 

• Even if they could be changed independently, in cases where both are being changed, there is 
a 100% performance penalty caused by being forced to invoke both utilities. 

The BSD syntax user[.gronp] was changed to user[:group] in this volume of IEEE Std. 1003.1-200x 
because the period is a valid character in login names (as specified by the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, login names consist of characters in the portable file 
name character set). The colon character was chosen as the replacement for the period character 
because it would never be allowed as a character in a user name or group name on historical 
implementations. 
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10614 The -R option is considered by some observers as an undesirable departure from the historical 

10615 UNIX system tools approach; since a tool, find, already exists to recurse over directories, there 

10616 seemed to be no good reason to require other tools to have to duplicate that functionality. 

10617 However, the -R option was deemed an important user convenience, is far more efficient than 

10618 forking a separate process for each element of the directory hierarchy, and is in widespread 

10619 historical use. 

10620 FUTURE DIRECTIONS 

10621 None. 

10622 SEE ALSO 

10623 chmod, chgrp, the System Interfaces volume of IEEE Std. 1003.1-200x, choivn () 

10624 CHANGE HISTORY 

10625 First released in Issue 2. 

10626 Issue 4 

10627 Aligned with the ISO/IEC 9945-2:1993 standard. I 

10628 Issue 6 I 

10629 New options -h, -H, -L, and -P are added to align with the IEEE P1003.2b draft standard. These I 

10630 options affect the processing of symbolic links. I 

10631 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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10632 NAME 

10633 cksum — write file checksums and sizes 


10634 SYNOPSIS 

10635 cksum [file ...] 


10636 DESCRIPTION 

10637 The cksum utility shall calculate and write to standard output a cyclic redundancy check (CRC) 

10638 for each input file, and also write to standard output the number of octets in each file. The CRC 

10639 used is based on the polynomial used for CRC error checking in the ISO/IEC 8802-3:1996 

10640 standard (Ethernet). 

10641 The encoding for the CRC checksum is defined by the generating polynomial: 

. 32 , 26 , 23 , 22 , 16 , 12 , 11 , 10 , 8 , 7 , 5 , 4 , 2 , , 

10642 G(x)=x +x +x +x +x +x +x +x +x + x +x +x +x +x+l 


10643 Mathematically, the CRC value corresponding to a given file shall be defined by the following 

10644 procedure: 


10645 

10646 

10647 

10648 

10649 

10650 

10651 

10652 

10653 


1. The n bits to be evaluated are considered to be the coefficients of a mod 2 polynomial M(x) 
of degree n— 1. These n bits are the bits from the file, with the most significant bit being the 
most significant bit of the first octet of the file and the last bit being the least significant bit 
of the last octet, padded with zero bits (if necessary) to achieve an integral number of 
octets, followed by one or more octets representing the length of the file as a binary value, 
least significant octet first. The smallest number of octets capable of representing this 
integer shall be used. 

2. M(x) is multiplied by x 32 (that is, shifted left 32 bits) and divided by C(x) using mod 2 
division, producing a remainder R(x) of degree <31. 


10654 3. The coefficients of R(x) are considered to be a 32-bit sequence. 

10655 4. The bit sequence is complemented and the result is the CRC. 


10656 OPTIONS 

10657 None. 


10658 OPERANDS 

10659 The following operand shall be supported: 

10660 file A path name of a file to be checked. If no file operands are specified, the standard 

10661 input is used. 

10662 STDIN 

10663 The standard input is used only if no file operands are specified. See the INPUT FILES section. 

10664 INPUT FILES 

10665 The input files can be any file type. 


10666 ENVIRONMENT VARIABLES 

10667 The following environment variables shall affect the execution of cksum: 


10668 

10669 

10670 

10671 

10672 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


10673 

10674 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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10675 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

10676 characters (for example, single-byte as opposed to multi-byte characters in 

10677 arguments). 

10678 LC_MESSAGES 

10679 Determine the locale that should be used to affect the format and contents of 

10680 diagnostic messages written to standard error. 

10681 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

10682 ASYNCHRONOUS EVENTS 

10683 Default. 

10684 STDOUT 

10685 For each file processed successfully, the cksum utility shall write in the following format: 

10686 "%u %d %s\n", <checksum>, <# of octets>, <pathname> 

10687 If no file operand was specified, the path name and its leading <space> shall be omitted. 

10688 STDERR 

10689 Used only for diagnostic messages. 

10690 OUTPUT FILES 

10691 None. 

10692 EXTENDED DESCRIPTION 

10693 None. 

10694 EXIT STATUS 

10695 The following exit values shall be returned: 

10696 0 All files were processed successfully. 

10697 >0 An error occurred. 

10698 CONSEQUENCES OF ERRORS 

10699 Default. 

10700 APPLICATION USAGE 

10701 The cksum utility is typically used to quickly compare a suspect file against a trusted version of 

10702 the same, such as to ensure that files transmitted over noisy media arrive intact. However, this 

10703 comparison cannot be considered cryptographically secure. The chances of a damaged file 

10704 producing the same CRC as the original are small; deliberate deception is difficult, but probably 

10705 not impossible. 

10706 Although input files to cksum can be any type, the results need not be what would be expected 

10707 on character special device files or on file types not described by the System Interfaces volume of 

10708 IEEE Std. 1003.1-200x. Since this volume of IEEE Std. 1003.1-200x does not specify the block size 

10709 used when doing input, checksums of character special files need not process all of the data in 

10710 those files. 

10711 The algorithm is expressed in terms of a bitstream divided into octets. If a file is transmitted 

10712 between two systems and undergoes any data transformation (such as moving 8-bit characters 

10713 into 9-bit bytes or changing little-endian byte ordering to big-endian), identical CRC values 

10714 cannot be expected. Implementations performing such transformations may extend cksum to 

10715 handle such situations. 
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10716 EXAMPLES 

10717 None. 

10718 RATIONALE 

10719 The following C-language program can be used as a model to describe the algorithm. It assumes 

10720 

that a char is one octet. It also assumes that the entire file is available for one pass through the 

10721 

function. This 

was done for simplicity in demonstrating the algorithm, rather than as an 

10722 

10723 

10724 

10725 

implementation model. 

static unsigned long crctabf] = { 
0x00000000, 

0x04clldb7, 0x09823b6e, 0x0d4326d9, 

0xl30476dc, 

0xl7c56b6b, 

10726 

0xla8 64db2, 

0xle475005, 

0x2608edb8, 

0x22c9fOOf, 

0x2f8ad6d6, 

10727 

0x2b4bcb61, 

0x350c9b64, 

0x31cd86d3, 

0x3c8ea00a, 

0x384fbdbd, 

10728 

0x4clldb70, 

0x4 8d0c6c7, 

0x4593e01e, 

0x4152fda9, 

0x5f15adac, 

10729 

0x5bd4b01b, 

0x569796c2, 

0x52568b75, 

0x6al93 6c8, 

0x6ed82b7f, 

10730 

0x639b0da6, 

0x675al011, 

0x791d4014, 

0x7ddc5da3, 

0x7 0 9f7b7a, 

10731 

0x745e66cd, 

0x9823b6e0, 

0x9ce2ab57, 

0x91al8d8e, 

0x95609039, 

10732 

0x8b27c03c, 

0x8fe6dd8b, 

0x82a5fb52, 

0x8664e6e5, 

0xbe2b5b58, 

10733 

0xbaea4 6ef, 

0xb7a96036, 

0xb3687d81, 

0xad2f2d84, 

0xa9ee3033, 

10734 

0xa4adl6ea, 

OxaO 6c0b5d, 

0xd4 32 6d90, 

OxdOf37027, 

0xddb056fe, 

10735 

0xd9714b49, 

0xc7361b4c, 

0xc3f706fb, 

0xceb42022, 

0xca753d95, 

10736 

0xf23a8028, 

Oxf 6fb9d9f, 

0xfbb8bb4 6, 

0xff79a6fl, 

0xel3ef6f4, 

10737 

0xe5ffeb43. 

0xe8bccd9a, 

0xec7dd02d, 

0x34867077, 

0x30476dc0, 

10738 

0x3d044bl9, 

0x39c556ae, 

0x278206ab, 

0x23431blc, 

0x2e003dc5, 

10739 

0x2acl2072, 

0xl28e9dcf, 

0xl64f8078, 

0xlb0ca6al, 

0xlfcdbbl6, 

10740 

0x018aebl3, 

0x054bf6a4, 

0x0808d07d, 

0x0cc9cdca, 

0x7897ab07, 

10741 

0x7c56b6b0, 

0x71159069, 

0x75d48dde, 

0x6b93dddb, 

0x6f52c0 6c, 

10742 

0x6211e6b5, 

0x66d0fb02, 

0x5e9f4 6bf, 

0x5a5e5b08, 

0x571d7ddl, 

10743 

0x53dc6066, 

0x4d9b3063, 

0x4 95a2dd4, 

0x44190b0d, 

0x40d816ba, 

10744 

0xaca5c697, 

0xa864db20, 

0xa527fdf9, 

0xale6e04e, 

0xbfalb04b, 

10745 

0xbb60adfc. 

0xb6238b25, 

0xb2e29692, 

0x8aad2b2f, 

0x8e6c3698, 

10746 

0x832f1041, 

0x87ee0df6, 

0x99a95df3, 

0x9d684044, 

0x902b669d, 

10747 

0x94ea7b2a, 

0xe0b4lde7, 

0xe4750050, 

Oxe 93 62 68 9, 

Oxedf73b3e, 

10748 

Oxf3b0 6b3b, 

Oxf7717 68c, 

Oxfa325055, 

0xfef34de2, 

0xc6bcf05f, 

10749 

0xc27dede8, 

Oxcf3ecb31, 

Oxcbffd686. 

0xd5b88683, 

0xdl7 99b34, 

10750 

0xdc3abded, 

0xd8fba05a, 

0x690ce0ee, 

0x6dcdfd59, 

0x608edb80, 

10751 

0x644fc637, 

0x7a089632, 

0x7ec98b85, 

0x738aad5c, 

0x774bb0eb, 

10752 

0x4f040d56, 

0x4bc510el, 

0x46863638, 

0x42472b8f, 

0x5c007b8a, 

10753 

0x58cl663d, 

0x558240e4, 

0x514 35d53, 

0x251d3b9e, 

0x21dc2629, 

10754 

0x2c9fOOf0, 

0x285eld47, 

0x36194d42, 

0x32d850f5, 

0x3f9b7 62c, 

10755 

0x3b5a6b9b, 

0x0315d626, 

0x07d4cb91, 

0x0a97ed4 8, 

0x0e56fOff, 

10756 

OxlOllaOfa, 

0xl4d0bd4d, 

0xl9939b94, 

0xld528623, 

Oxf12f560e, 

10757 

Oxf5ee4bb9, 

Oxf8ad6d60, 

Oxfc6c7 0d7, 

0xe22b20d2, 

0xe6ea3d65, 

10758 

0xeba91bbc, 

Oxef68060b, 

0xd727bbb6, 

0xd3e6a601, 

0xdea580d8, 

10759 

0xda64 9d6f, 

0xc423cd6a, 

0xc0e2d0dd, 

Oxcdalf604, 

0xc960ebb3, 

10760 

0xbd3e8d7e, 

0xb9ff90c9, 

0xb4bcb610, 

0xb07daba7, 

0xae3afba2, 

10761 

0xaafbe615, 

0xa7b8c0cc, 

0xa379dd7b, 

0x9b3660c6, 

0x9ff77d71, 

10762 

0x92b45ba8, 

0x96754 61f, 

0x8832161a, 

0x8cf30bad, 

0x81b02d74, 

10763 

0x857130c3, 

0x5d8a9099, 

0x594b8d2e, 

0x5408abf7, 

0x50c9b640, 

10764 

0x4e8ee645, 

0x4a4ffbf2, 

0x4 7 0cdd2b, 

0x4 3cdc0 9c, 

0x7b827d21, 

10765 

0x7f436096, 

0x7200464f, 

0x76cl5bf8, 

0x68860bfd, 

0x6c47164a, 

10766 

0x61043093, 

0x65c52d24, 

0xll9b4be9, 

0xl55a565e, 

0x18197087, 


Commands and Utilities, Issue 6 


285 



cksum 


Utilities 


10767 

10768 

10769 

10770 

10771 

10772 

10773 

10774 

10775 

10776 

10777 

10778 

10779 

10780 

10781 

10782 

10783 

10784 

10785 

10786 

10787 

10788 

10789 

10790 

10791 

10792 

10793 

10794 

10795 

10796 

10797 

10798 

10799 

10800 
10801 
10802 

10803 

10804 

10805 

10806 

10807 

10808 

10809 

10810 
10811 
10812 

10813 

10814 


0xlcd86d30, 
0x3793a651, 
0x2056cd3a, 
0xcc2bldl7, 
0xdbee767c, 
Oxf0a5bdld, 
0x8d7 9e0be, 
0x933eb0bb, 
0xa2f33668, 
}; 


0x029f3d35, 
0x3352bbe6, 
0x2dl5ebe3, 
0xc8ea00a0, 
0xe3alcbcl, 
Oxf4 64a0aa, 
0x803ac667, 
0x97ffadOc, 
0xbcb4 666d, 


0x065e2082, 
0x3ell9d3f, 
0x29d4f654, 
0xd6ad50a5, 
0xe760d676, 
Oxf9278673, 
0x84fbdbd0, 
OxafbOlObl, 
0xb8757bda, 


OxObldO 65b, 
0x3ad08088, 
0xc5a92679, 
0xd2 6c4dl2, 
0xea23fOaf, 
0xfde69bc4, 
0x9abc8bd5, 
0xab710d06, 
0xb5365d03, 


OxOfdclbec, 
0x24 97d08d, 
0xcl683bce, 
0xdf2f6bcb, 
0xeee2edl8, 
0x89b8fd09, 
0x9e7d9662, 
0xa6322bdf, 
Oxblf740b4 


unsigned long memcrc(const unsigned char *b, size_t n) 

{ 

/* Input arguments: 

* const char* b == byte sequence to checksum 

* size_t n == length of sequence 

*/ 


register unsigned int i, c, s = 0; 

for (i = n; i > 0; —i) { 

c = (unsigned int)(*b++); 
s = (s << 8) ~ crctab[(s >> 24) * c]; 

} 


/* Extend with the length of the string. */ 
while (n != 0) { 

c = n & 0377; 
n >>= 8; 

s = (s << 8) ~ crctab[(s >> 24) " c]; 

} 


return ~s; 

} 


The historical practice of writing the number of "blocks” has been changed to writing the 
number of octets, since the latter is not only more useful, but also since historical 
implementations have not been consistent in defining what a "block" meant. Octets are used 
instead of bytes because bytes can differ in size between systems. 

The algorithm used was selected to increase the operational robustness of cksum. Neither the 
System V nor BSD sum algorithm was selected. Since each of these was different and each was 
the default behavior on those systems, no realistic compromise was available if either were 
selected—some set of historical applications would break. Therefore, the name was changed to 
cksum. Although the historical sum commands will probably continue to be provided for many 
years, programs designed for portability across systems should use the new name. 

The algorithm selected is based on that used by the ISO/IEC 8802-3:1996 standard (Ethernet) for 
the frame check sequence field. The algorithm used does not match the technical definition of a 
checksum - the term is used for historical reasons. The length of the file is included in the CRC 
calculation because this parallels inclusion of a length field by Ethernet in its CRC, but also 
because it guards against inadvertent collisions between files that begin with different series of 
zero octets. The chance that two different files produce identical CRCs is much greater when 
their lengths are not considered. Keeping the length and the checksum of the file itself separate 
would yield a slightly more robust algorithm, but historical usage has always been that a single 
number (the checksum as printed) represents the signature of the file. It was decided that 
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10815 historical usage was the more important consideration. 

10816 Early proposals contained modifications to the Ethernet algorithm that involved extracting table 

10817 values whenever an intermediate result became zero. This was demonstrated to be less robust 

10818 than the current method and mathematically difficult to describe or justify. 

10819 The calculation used is identical to that given in pseudo-code in the referenced Sarwate Article. 

10820 The pseudo-code rendition is: 


10821 

10822 

10823 

10824 

10825 

10826 

10827 

10828 
10829 


X <- 0; Y <- 0; 

for i <— m —1 step —1 until 0 do 
begin 

T <- X (1) ~ A [ i ] ; 

x (1) <- X (0) ; X (0 ) <- Y (1) ; Y(l) <- Y (0) ; Y (0) <- 0; 
comment: f[T] and f'[T] denote the T-th words in the 
table f and f' ; 

X <- X ~ f [T] ; Y <- Y * f [T] ; 
end 


10830 The pseudo-code is reproduced exactly as given; however, note that in the case of cksum , A[i] 

10831 represents a byte of the file, the words X and Y are treated as a single 32-bit value, and the tables 

10832 f and f' are a single table containing 32-bit values. 

10833 The referenced Sarwate Article also discusses generating the table. 

10834 FUTURE DIRECTIONS 

10835 None. 


10836 SEE ALSO 

10837 None. 


10838 CHANGE HISTORY 

10839 First released in Issue 4. 
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10840 NAME 

10841 cmp — compare two files 

10842 SYNOPSIS 

10843 cmp [ —1 | — s ] filel file2 

10844 DESCRIPTION 

10845 The cmp utility shall compare two files. The cmp utility writes no output if the files are the same. 

10846 Under default options, if they differ, it shall write to standard output the byte and line number at 

10847 which the first difference occurred. Bytes and lines shall be numbered beginning with 1. 

10848 OPTIONS 

10849 The cmp utility shall conform to the System Interface Definitions volume of I 

10850 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 


10851 

The following options shall be supported: 

10852 

-1 

(Lowercase ell.) Write the byte number (decimal) and the differing bytes (octal) for 

10853 


each difference. 

10854 

-s 

Write nothing for differing files; return exit status only. 

10855 OPERANDS 


10856 

The following operands shall be supported: 

10857 

filel 

A path name of the first file to be compared, li filel is ' , the standard input shall 

10858 


be used. 

10859 

file2 

A path name of the second file to be compared, li file! is ' , the standard input 

10860 


shall be used. 


10861 If both filel and file2 refer to standard input or refer to the same FIFO special, block special, or 

10862 character special file, the results are undefined. 

10863 STDIN 

10864 The standard input shall be used only if th e filel or file! operand refers to standard input. See the 

10865 INPUT FILES section. 


10866 INPUT FILES 

10867 The input files can be any file type. 


10868 ENVIRONMENT VARIABLES 

10869 The following environment variables shall affect the execution of cmp: 


10870 

10871 

10872 

10873 

10874 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


10875 

10876 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


10877 

10878 

10879 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


10880 

10881 

10882 

10883 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 
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10884 

10885 

10886 

10887 

10888 

10889 

10890 

10891 

10892 

10893 

10894 

10895 

10896 

10897 

10898 

10899 

10900 

10901 

10902 

10903 

10904 

10905 

10906 

10907 

10908 

10909 

10910 

10911 

10912 

10913 

10914 

10915 

10916 

10917 

10918 

10919 

10920 

10921 

10922 

10923 

10924 


xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

In the POSIX locale, results of the comparison shall be written to standard output. When no 
options are used, the format shall be: 

"%s %s differ: char %d, line %d\n", filel, file2, 

<byte number>, <line number> 

When the -1 option is used, the format shall be: 

"%d %o %o\n", <byte number>, <differing byte>, 

<differing byte> 

for each byte that differs. The first <differing byte> number is from filel while the second is from 
file2 . In both cases, <byte nnmber> shall be relative to the beginning of the file, beginning with 1. 

No output shall be written to standard output when the -s option is used. 

STDERR 

Used only for diagnostic messages. If filel and file2 are identical for the entire length of the 
shorter file, in the POSIX locale the following diagnostic message shall be written, unless the -s 
option is specified: 

"cmp: EOF on %s%s\n", <name of shorter file>, <additional info> 

The additional info> field shall either be null or a string that starts with a <blank> character and 
contains no <newline> characters. Some systems report on the number of lines in this case. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The files are identical. 

1 The files are different; this includes the case where one file is identical to the first part of the 
other. 

>1 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Although input files to cmp can be any type, the results might not be what would be expected on 
character special device files or on file types not described by the System Interfaces volume of 
IEEE Std. 1003.1-200x. Since this volume of IEEE Std. 1003.1-200x does not specify the block size 
used when doing input, comparisons of character special files need not compare all of the data 
in those files. 

For files which are not text files, line numbers simply reflect the presence of a <newline> 
character, without any implication that the file is organized into lines. 
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10925 EXAMPLES 

10926 None. 

10927 RATIONALE 

10928 The global language in Section 1.11 on page 25 indicates that using two mutually-exclusive 

10929 options together produces unspecified results. Some System V implementations consider the 

10930 option usage: 

10931 cmp -1 -s ... 

10932 to be an error. They also treat: 

10933 cmp —s -1 ... 

10934 as if no options were specified. Both of these behaviors are considered bugs, but are allowed. 

10935 The word char in the standard output format comes from historical usage, even though it is 

10936 actually a byte number. When cmp is supported in other locales, implementations are 

10937 encouraged to use the word byte or its equivalent in another language. Users should not 

10938 interpret this difference to indicate that the functionality of the utility changed between locales. 

10939 Some systems report on the number of lines in the identical-but-shorter file case. This is allowed 

10940 by the inclusion of the <additional info fields in the output format. The restriction on having a 

10941 leading <blank> and no <newline>s is to make parsing for the file name easier. It is recognized 

10942 that some file names containing white-space characters make parsing difficult anyway, but the 

10943 restriction does aid programs used on systems where the names are predominantly well 

10944 behaved. 

10945 FUTURE DIRECTIONS 

10946 None. 

10947 SEE ALSO 

10948 comm, diff 

10949 CHANGE HISTORY 

10950 First released in Issue 2. 

10951 Issue 4 

10952 Aligned with the ISO/IEC 9945-2:1993 standard. 
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10953 NAME 

10954 comm — select or reject lines common to two files 

10955 SYNOPSIS 

10956 comm [—123] filel file2 

10957 DESCRIPTION 

10958 The comm utility shall read filel and file !, which should be ordered in the current collating 

10959 sequence, and produce three text columns as output: lines only in filel, lines only in file2, and 

10960 lines in both files. 


10961 If the lines in both files are not ordered according to the collating sequence of the current locale, 

10962 the results are unspecified. 


10963 OPTIONS 

10964 The comm utility shall conform to the System Interface Definitions volume of I 

10965 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

10966 The following options shall be supported: 

10967 -1 Suppress the output column of lines unique to filel. 

10968 -2 Suppress the output column of lines unique to file!. 

10969 -3 Suppress the output column of lines duplicated in filel and filel . 

10970 OPERANDS 

10971 The following operands shall be supported: 

10972 filel A path name of the first file to be compared. If filel is the standard input is 

10973 used. 


10974 filel A path name of the second file to be compared. It filel is ' , the standard input is 

10975 used. 


10976 If both filel and filel refer to standard input or to the same FIFO special, block special, or 

10977 character special file, the results are undefined. 

10978 STDIN 

10979 The standard input shall be used only if one of the filel or filel operands refers to standard input. 

10980 See the INPUT FILES section. 


10981 INPUT FILES 

10982 The input files shall be text files. 


10983 ENVIRONMENT VARIABLES 

10984 The following environment variables shall affect the execution of comm: 


10985 

10986 

10987 

10988 

10989 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


10990 LC_ALL If set to a non-empty string value, override the values of all the other 

10991 internationalization variables. 


10992 LC_COLLATE 

10993 Determine the locale for the collating sequence comm expects to have been used 

10994 when the input files were sorted. 
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10995 

10996 

10997 

10998 

10999 

11000 

11001 

11002 

11003 

11004 

11005 

11006 

11007 

11008 

11009 

11010 
11011 
11012 

11013 

11014 

11015 

11016 

11017 

11018 

11019 

11020 
11021 

11022 

11023 

11024 

11025 

11026 

11027 

11028 

11029 

11030 

11031 


LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The comm utility shall produce output depending on the options selected. If the -1, -2, and -3 
options are all selected, comm shall write nothing to standard output. 

If the -1 option is not selected, lines contained only in filel shall be written using the format: 

"%s\n", <line in filel> 

If the -2 option is not selected, lines contained only in file! are written using the format: 
"%s%s\n", <lead>, <line in file2> 
where the string <lead> is as follows: 

<tab> The -1 option is not selected, 

null string The -1 option is selected. 

If the -3 option is not selected, lines contained in both files shall be written using the format: 
"%s%s\n", <lead>, <line in both> 
where the string <lead> is as follows: 

<tabxtab> Neither the -1 nor the -2 option is selected. 

<tab> Exactly one of the -1 and -2 options is selected, 

null string Both the -1 and -2 options are selected. 

If the input files were ordered according to the collating sequence of the current locale, the lines 
written shall be in the collating sequence of the original lines. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 All input files were successfully output as specified. 

>0 An error occurred. 
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11032 

11033 

11034 

11035 

11036 

11037 

11038 

11039 

11040 

11041 

11042 

11043 

11044 

11045 

11046 

11047 

11048 

11049 

11050 

11051 

11052 

11053 

11054 

11055 

11056 

11057 

11058 

11059 

11060 


CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

If the input files are not properly presorted, the output of comm might not be useful. 

EXAMPLES 

If a file named xcu contains a sorted list of the utilities in this volume of IEEE Std. 1003.1-200x, a 
file named xpg3 contains a sorted list of the utilities specified in the X/Open Portability Guide, 
Issue 3, and a file named svid89 contains a sorted list of the utilities in the System V Interface 
Definition Third Edition: 

comm —23 xcu xpg3 | comm —23 — svid89 

would print a list of utilities in this volume of IEEE Std. 1003.1-200x not specified by either of the 
other documents: 

comm —12 xcu xpg3 | comm —12 — svid89 

would print a list of utilities specified by all three documents, and: 

comm —12 xpg3 svid89 I comm —23 — xcu 

would print a list of utilities specified by both XPG3 and the SVID, but not specified in this 
volume of IEEE Std. 1003.1-200x. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

cmp, diff, sort, uniq 

CHANGE HISTORY 

First released in Issue 2. 

Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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11061 NAME 

11062 command — execute a simple command 

11063 SYNOPSIS 

11064 command [—p] command_name [argument ...] 

11065 UP command [ —v | —V ] command_name 

11066 

11067 DESCRIPTION 

11068 The command utility shall cause the shell to treat the arguments as a simple command, 

11069 suppressing the shell function lookup that is described in Section 2.9.1.1 on page 69, item lb. 

11070 If the command_name is the same as the name of one of the special built-in utilities, the special 

11071 properties in the enumerated list at the beginning of Section 2.14 on page 96 shall not occur. In 

11072 every other respect, if command_name is not the name of a function, the effect of command shall be 

11073 the same as omitting command. 

11074 On systems supporting the User Portability Utilities option, the command utility also shall 

11075 provide information concerning how a command name is interpreted by the shell; see -v and 

11076 -V. 


11077 OPTIONS 

11078 The command utility shall conform to the System Interface Definitions volume of I 

11079 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

11080 The following options shall be supported: 

11081 -p Perform the command search using a default value for PATH that is guaranteed to 

11082 find all of the standard utilities. 


11083 -v 

11084 

11085 

11086 


(On systems supporting the User Portability Utilities option.) Write a string to 
standard output that indicates the path name or command that will be used by the 
shell, in the current shell execution environment (see Section 2.12 on page 90), to 
invoke command_name. 


11087 

11088 

11089 

11090 


• Utilities, regular built-in utilities, command_name s including a slash character, 
and any implementation-dependent functions that are found using the PATH 
variable (as described in Section 2.9.1.1 on page 69), shall be written as absolute 
path names. 


11091 

11092 

11093 


• Shell functions, special built-in utilities, regular built-in utilities not associated 
with a PATH search, and shell reserved words shall be written as just their 
names. 


11094 


• An alias shall be written as a command line that represents its alias definition. 


11095 

11096 


• Otherwise, no output shall be written and the exit status shall reflect that the 
name was not found. 


11097 

11098 

11099 

11100 
11101 
11102 


-V (On systems supporting the User Portability Utilities option.) Write a string to 

standard output that indicates how the name given in the command_name operand 
will be interpreted by the shell, in the current shell execution environment (see 
Section 2.12 on page 90). Although the format of this string is unspecified, it shall 
indicate in which of the following categories command_name falls and shall include 
the information stated: 


11103 

11104 

11105 


• Utilities, regular built-in utilities, and any implementation-dependent functions 
that are found using the PATH variable (as described in Section 2.9.1.1 on page 
69), shall be identified as such and include the absolute path name in the string. 
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11106 

11107 

11108 

11109 

11110 

11111 

11112 

11113 

11114 

11115 

11116 

11117 

11118 

11119 

11120 

11121 

11122 

11123 

11124 

11125 

11126 

11127 

11128 

11129 

11130 

11131 

11132 

11133 

11134 

11135 

11136 

11137 

11138 

11139 

11140 

11141 

11142 

11143 

11144 

11145 

11146 


• Other shell functions shall be identified as functions. 

• Aliases shall be identified as aliases and their definitions included in the string. 

• Special built-in utilities shall be identified as special built-in utilities. 

• Regular built-in utilities not associated with a PATH search shall be identified 
as regular built-in utilities. (The term "regular" need not be used.) 

• Shell reserved words shall be identified as reserved words. 


OPERANDS 

The following operands shall be supported: 

argument One of the strings treated as an argument to command_name. 
command_name 

The name of a utility or a special built-in utility. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of command: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Determine the search path used during the command search described in Section 

2.9.1.1 on page 69, except as described under the -p option. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

When the -v option is specified, standard output shall be formatted as: 

"%s\n", <pathname or command> 

When the -V option is specified, standard output shall be formatted as: 

"%s\n", <unspecified> 


Commands and Utilities, Issue 6 


295 



command 


Utilities 


11147 STDERR 

11148 Used only for diagnostic messages. 

11149 OUTPUT FILES 

11150 None. 

11151 EXTENDED DESCRIPTION 

11152 None. 

11153 EXIT STATUS 

11154 When the -v or -V options are specified, the following exit values shall be returned: 

11155 0 Successful completion. 

11156 >0 The command_name could not be found or an error occurred. 

11157 Otherwise, the following exit values shall be returned: 

11158 1 26 The utility specified by command_name was found but could not be invoked. 

11159 127 An error occurred in the command utility or the utility specified by command_name could not 

11160 be found. 

11161 Otherwise, the exit status of command shall be that of the simple command specified by the 

11162 arguments to command. 

11163 CONSEQUENCES OF ERRORS 

11164 Default. 

11165 APPLICATION USAGE 

11166 The order for command search allows functions to override regular built-ins and path searches. 

11167 This utility is necessary to allow functions that have the same name as a utility to call the utility 

11168 (instead of a recursive call to the function). 

11169 The system default path is available using getconf; however, since getconf may need to have the 

11170 PATH set up before it can be called itself, the following can be used: 

11171 command —p getconf _CS_PATH 

11172 There are some advantages to suppressing the special characteristics of special built-ins on 

11173 occasion. For example: 

11174 command exec > unwritable-file 

11175 does not cause a non-interactive script to abort, so that the output status can be checked by the 

11176 script. 

11177 The command, env, nohup, time, and xargs utilities have been specified to use exit code 127 if an 

11178 error occurs so that applications can distinguish "failure to find a utility" from "invoked utility 

11179 exited with an error indication". The value 127 was chosen because it is not commonly used for 

11180 other meanings; most utilities use small values for "normal error conditions" and the values 

11181 above 128 can be confused with termination due to receipt of a signal. The value 126 was chosen 

11182 in a similar manner to indicate that the utility could be found, but not invoked. Some scripts 

11183 produce meaningful error messages differentiating the 126 and 127 cases. The distinction 

11184 between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 

11185 exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 

11186 any other reason. 

11187 Since the -v and -V options of command produce output in relation to the current shell execution 

11188 environment, command is generally provided as a shell regular built-in. If it is called in a subshell 

11189 or separate utility execution environment, such as one of the following: 
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11190 

11191 

11192 

11193 

11194 

11195 

11196 

11197 

11198 

11199 

11200 
11201 
11202 

11203 

11204 

11205 

11206 

11207 

11208 

11209 

11210 

11211 

11212 

11213 

11214 

11215 

11216 

11217 

11218 

11219 

11220 

11221 

11222 

11223 

11224 

11225 

11226 

11227 

11228 

11229 

11230 

11231 

11232 

11233 

11234 


(PATH=foo command —v) 
nohup command —v 

it does not necessarily produce correct results. For example, when called with nohup or an exec 
function, in a separate utility execution environment, most implementations are not able to 
identify aliases, functions, or special built-ins. 

Two types of regular built-ins could be encountered on a system and these are described 
separately by command. The description of command search in Section 2.9.1.1 on page 69 allows 
for a standard utility to be implemented as a regular built-in as long as it is found in the 
appropriate place in a PATH search. So, for example, command -v true might yield /bin/true or 
some similar path name. Other implementation-dependent utilities that are not defined by this 
volume of IEEE Std. 1003.1-200x might exist only as built-ins and have no path name associated 
with them. These produce output identified as (regular) built-ins. Applications encountering 
these are not able to count on exec ing them, using them with nohup, overriding them with a 
different PATH, and so on. 

EXAMPLES 

1. Make a version of cd that always prints out the new working directory exactly once: 

cd () { 

command cd "$@" >/dev/null 
pwd 

} 

2. Start off a "secure shell script" in which the script avoids being spoofed by its parent: 

IFS = ' 


# The preceding value should be <space><tab><newline>. 

# Set IFS to its default value. 

\unalias —a 

# Unset all possible aliases. 

# Note that unalias is escaped to prevent an alias 

# being used for unalias. 

unset —f command 

# Ensure command is not a user function. 

PATH="$(command -p getconf _CS_PATH):$PATH" 

# Put on a reliable PATH prefix. 

# 

At this point, given correct permissions on the directories called by PATH, the script has 
the ability to ensure that any utility it calls is the intended one. It is being very cautious 
because it assumes that implementation extensions may be present that would allow user 
functions to exist when it is invoked; this capability is not specified by this volume of 
IEEE Std. 1003.1-200x, but it is not prohibited as an extension. For example, the ENV I 
variable precedes the invocation of the script with a user start-up script. Such a script I 
could define functions to spoof the application. 

RATIONALE 

Since command is a regular built-in utility it is always found prior to the PATH search. 

There is nothing in the description of command that implies the command line is parsed any 
differently from that of any other simple command. For example: 
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11235 

11236 

11237 

11238 

11239 

11240 

11241 

11242 

11243 

11244 

11245 

11246 

11247 

11248 

11249 

11250 

11251 

11252 

11253 

11254 

11255 

11256 

11257 

11258 

11259 

11260 
11261 
11262 

11263 

11264 

11265 

11266 

11267 

11268 

11269 

11270 

11271 

11272 

11273 

11274 


command a I b ; c 

is not parsed in any special way that causes ' |' or ';' to be treated other than a pipe operator 
or semicolon or that prevents function lookup on b or c. 

The command utility is somewhat similar to the Eighth Edition shell builtin command, but since 
command also goes to the file system to search for utilities, the name builtin would not be 
intuitive. 

The command utility is most likely to be provided as a regular built-in. It is not listed as a special 
built-in for the following reasons: 

• The removal of exportable functions made the special precedence of a special built-in 
unnecessary. 

• A special built-in has special properties (see Section 2.14 on page 96) that were inappropriate 
for invoking other utilities. For example, two commands such as: 

date > unwritable-file 

command date > unwritable-file 

would have entirely different results; in a non-interactive script, the former would continue 
to execute the next command, the latter would abort. Introducing this semantic difference 
along with suppressing functions was seen to be non-intuitive. 

The -p option is present because it is useful to be able to ensure a safe path search that finds all 
the POSIX Shell and Utilities standard utilities. This search might not be identical to the one that 
occurs through one of the POSIX System Interfaces exec functions when PATH is unset. At the 
very least, this feature is required to allow the script to access the correct version of getconf so 
that the value of the default path can be accurately retrieved. 

The command -v and -V options were added to satisfy requirements from users that are 
currently accomplished by three different historical utilities: type in the System V shell, whence in 
the KomShell, and which in the C shell. Since there is no historical agreement on how and what 
to accomplish here, the POSIX command utility was enhanced and the historical utilities were left 
unmodified. The C shell which merely conducts a path search. The KornShell whence is more 
elaborate—in addition to the categories required by POSIX, it also reports on tracked aliases, 
exported aliases, and undefined functions. 

The output format of -V was left mostly unspecified because human users are its only audience. 
Applications should not be written to care about this information; they can use the output of -v 
to differentiate between various types of commands, but the additional information that may be 
emitted by the more verbose -V is not needed and should not be arbitrarily constrained in its 
verbosity or localization for application parsing reasons. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

sh, type 

CHANGE HISTORY 

First released in Issue 4. 
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11275 NAME 

11276 compress — compress data 

11277 SYNOPSIS 

11278 xsi compress [—fv] [—b bits] [file . . . ] 

11279 compress [—cfv] [— b bits ] [file] 

11280 


11281 DESCRIPTION 

11282 The compress utility shall attempt to reduce the size of the named files by using adaptive 

11283 Lempel-Ziv coding. Except when the output is to the standard output, each file shall be replaced 

11284 by one with the extension .Z. If the invoking process has appropriate privileges, the ownership, 

11285 modes, access time, and modification time of the original file are preserved. If appending the .Z 

11286 to the file name would make the name exceed |NAME_MAX} bytes, the command shall fail. If 

11287 no files are specified, the standard input shall be compressed to the standard output. 


11288 OPTIONS 

11289 The compress utility shall conform to the System Interface Definitions volume of I 

11290 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

11291 The following options shall be supported: 


11292 -b bits Specify the maximum number of bits to use in a code. For a portable application, 

11293 the bits argument shall be: 


11294 


9 <= bits <= 14 


11295 

11296 


The implementation may allow bits values of greater than 14. The default is 14,15, 
or 16. 


11297 -c Cause compress to write to the standard output; the input file is not changed, and 

11298 no .Z files are created. 


11299 -f 

11300 

11301 

11302 


Force compression otfile, even if it does not actually reduce the size of the file, or if 
the corresponding file.Z file already exists. If the -f option is not given, and the 
process is not running in the background, the user is prompted as to whether an 
existing file.Z file should be overwritten. 


11303 -v 


Write the percentage reduction of each file to standard error. 


11304 OPERANDS 

11305 The following operand shall be supported: 


11306 file A path name of a file to be compressed. 


11307 STDIN 

11308 The standard input shall be used only if no file operands are specified, or if a file operand is ' . 


11309 INPUT FILES 

11310 If file operands are specified, the input files contain the data to be compressed. 


11311 ENVIRONMENT VARIABLES 

11312 The following environment variables shall affect the execution of compress: 

11313 LANG Provide a default value for the internationalization variables that are unset or null. 

11314 If LANG is unset or null, the corresponding value from the implementation- 

11315 dependent default locale shall be used. If any of the internationalization variables 

11316 contains an invalid setting, the utility shall behave as if none of the variables had 

11317 been defined. 
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11318 LC_ALL If set to a non-empty string value, override the values of all the other 

11319 internationalization variables. 

11320 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

11321 characters (for example, single-byte as opposed to multi-byte characters in 

11322 arguments). 

11323 LC_MESSAGES 

11324 Determine the locale that should be used to affect the format and contents of 

11325 diagnostic messages written to standard error. 

11326 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

11327 ASYNCHRONOUS EVENTS 

11328 Default. 

11329 STDOUT 

11330 If no file operands are specified, or if a file operand is or if the -c option is specified, the 

11331 standard output contains the compressed output. 

11332 STDERR 

11333 Used for all diagnostic and prompt messages and the output from -v. 

11334 OUTPUT FILES 

11335 The output files shall contain the compressed output. 

11336 EXTENDED DESCRIPTION 

11337 None. 

11338 EXIT STATUS 

11339 The following exit values shall be returned: 

11340 0 Successful completion. 

11341 1 An error occurred. 

11342 2 One or more files were not compressed because they would have increased in size (and the 

11343 -f option was not specified). 

11344 >2 An error occurred. 

11345 CONSEQUENCES OF ERRORS 

11346 The input file shall remain unmodified. 

11347 APPLICATION USAGE 

11348 The amount of compression obtained depends on the size of the input, the number of bits per 

11349 code, and the distribution of common substrings. Typically, text such as source code or English 

11350 is reduced by 50-60%. Compression is generally much better than that achieved by Huffman 

11351 coding or adaptive Huffman coding (compact), and takes less time to compute. 

11352 Although compress strictly follows the default actions upon receipt of a signal or when an error 

11353 occurs, some unexpected results may occur. In some implementations it is likely that a partially 

11354 compressed file is left in place, alongside its uncompressed input file. Since the general 

11355 operation of compress is to delete the uncompressed file only after the .Z file has been 

11356 successfully filled, an application should always carefully check the exit status of compress before 

11357 arbitrarily deleting files that have like-named neighbors with .Z suffixes. 

11358 Compressed files are not necessarily portable to other systems. 

11359 The limit of 14 on the bits option-argument is to achieve portability to all systems (within the 

11360 restrictions imposed by the lack of an explicit published file format). Some systems based on 
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11361 16-bit architectures cannot support 15 or 16-bit uncompression. 

11362 EXAMPLES 

11363 None. 

11364 RATIONALE 

11365 None. 

11366 FUTURE DIRECTIONS 

11367 None. 

11368 SEE ALSO 

11369 uncompress , zcat 

11370 CHANGE HISTORY 

11371 First released in Issue 4. 

11372 Issue 4, Version 2 

11373 The DESCRIPTION section is clarified to state that the ownership, modes, access time, and 

11374 modification time of the original file are preserved if the invoking process has appropriate 

11375 privileges. 

11376 The STDOUT section includes the case where a file operand is ' . 

11377 Issue 6 

11378 The normative text is reworded to avoid use of the term "must” for application requirements. 
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11379 NAME 

11380 cp — copy files 

11381 SYNOPSIS 

11382 cp [—fip] source_file target_file 

11383 cp [-fip] source_file . . . target 

11384 cp -R [—H | -L | -P] [-fip] source_file . . . target I 

11385 cp —r [—H | -L | -P] [-fip] source_file . . . target I 

11386 DESCRIPTION | 

11387 The first synopsis form is denoted by two operands, neither of which are existing files of type 

11388 directory. The cp utility shall copy the contents of sourceJile (or, if sourcejile is a file of type I 

11389 symbolic link, the contents of the file referenced by source_file) to the destination path named by I 

11390 target_file. 

11391 The second synopsis form is denoted by two or more operands where the -R or -r options are 

11392 not specified and the first synopsis form is not applicable. It shall be an error if any source Jile is a 

11393 file of type directory, if target does not exist, or if target is a file of a type defined by the System 

11394 Interfaces volume of IEEE Std. 1003.1-200x, but is not a file of type directory. The cp utility shall 

11395 copy the contents of each sourcejile (or, if sourceJile is a file of type symbolic link, the contents I 

11396 of the file referenced by sourceJile) to the destination path named by the concatenation of target, I 

11397 a slash character, and the last component of source Jile. 

11398 The third and fourth synopsis forms are denoted by two or more operands where the -R or -r 

11399 options are specified. The cp utility shall copy each file in the file hierarchy rooted in each 

11400 source_file to a destination path named as follows. 

11401 If target exists and is a file of type directory, the name of the corresponding destination path for 

11402 each file in the file hierarchy shall be the concatenation of target, a slash character, and the path 

11403 name of the file relative to the directory containing source_file. 

11404 If target does not exist and two operands are specified, the name of the corresponding 

11405 destination path for source_file shall be target ; the name of the corresponding destination path for 

11406 all other files in the file hierarchy shall be the concatenation of target, a slash character, and the 

11407 path name of the file relative to source_file. 

11408 It shall be an error if target does not exist and more than two operands are specified, or if target 

11409 exists and is a file of a type defined by the System Interfaces volume of IEEE Std. 1003.1-200x, 

11410 but is not a file of type directory. 

11411 In the following description, the term dest_file refers to the file named by the destination path. I 

11412 The term source_file refers to the file that is being copied, whether specified as an operand or a I 

11413 file in a file hierarchy rooted in a source_file operand. If source Jile is a file of type symbolic link: I 

11414 • If neither the -R nor -r options were specified, cp shall take actions based on the type and I 

11415 contents of the file referenced by the symbolic link, and not by the symbolic link itself. I 

11416 • If the -R option was specified: I 

11417 — If none of the options -H, -L, nor -P were specified, it is unspecified which of -H, -L, or I 

11418 -P will be used as a default. I 

11419 — If the -H option was specified, cp shall take actions based on the type and contents of the I 

11420 file referenced by any symbolic link specified as a source,Jile operand. I 

11421 — If the -L option was specified, cp shall take actions based on the type and contents of the I 

11422 file referenced by any symbolic link specified as a source Jile operand or any symbolic I 
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links encountered during traversal of a file hierarchy. I 

— If the -P option was specified, cp shall copy any symbolic link specified as a sourcejile I 

operand and any symbolic links encountered during traversal of a file hierarchy, and shall I 

not follow any symbolic links. I 

• If the -r option was specified, the behavior is implementation-dependent. I 

For each source_file, the following steps shall be taken: I 

1. If sourceJile references the same file as destjile, cp may write a diagnostic message to 
standard error; it shall do nothing more with source Jile and shall go on to any remaining 
files. 

2. If source_file is of type directory, the following steps shall be taken: 

a. If neither the -R or -r options were specified, cp shall write a diagnostic message to 
standard error, do nothing more with sourcejile, and go on to any remaining files. 

b. If sourceJile was not specified as an operand and source_file is dot or dot-dot, cp shall 
do nothing more with source_file and go on to any remaining files. 

c. If dest_file exists and it is a file type not specified by the System Interfaces volume of 
IEEE Std. 1003.1-200x, the behavior is implementation-dependent. 

d. If dest_file exists and it is not of type directory, cp shall write a diagnostic message to 
standard error, do nothing more with sourcejile or any files below source_file in the 
file hierarchy, and go on to any remaining files. 

e. If the directory dest_file does not exist, it shall be created with file permission bits set 
to the same value as those of source Jile, modified by the file creation mask of the 
user if the -p option was not specified, and then bitwise-inclusively OR'ed with 
S_IRWXU. If destjile cannot be created, cp shall write a diagnostic message to 
standard error, do nothing more with source Jile, and go on to any remaining files. It 
is unspecified if cp attempts to copy files in the file hierarchy rooted in source_file. 

f. The files in the directory source_file shall be copied to the directory dest_file, taking 
the four steps [1-4] listed here with the files as sourcejile s. 

g. If dest_file was created, its file permission bits shall be changed (if necessary) to be the 
same as those of source_file, modified by the file creation mask of the user if the -p 
option was not specified. 

h. The cp utility shall do nothing more with source_file and go on to any remaining files. 

3. If source_file is of type regular file, the following steps shall be taken: 

a. If destjile exists, the following steps shall be taken: 

i. If the -i option is in effect, the cp utility shall write a prompt to the standard 
error and read a line from the standard input. If the response is not affirmative, 
cp shall do nothing more with source_file and go on to any remaining files. 

ii. A file descriptor for dest_file shall be obtained by performing actions equivalent 
to the open() function defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x called using dest_file as the path argument, and the 
bitwise-inclusive OR of 0_WR0NLY and 0_TRUNC as the oflag argument. 

iii. If the attempt to obtain a file descriptor fails and the -f option is in effect, cp 
shall attempt to remove the file by performing actions equivalent to the 
unlink () function defined in the System Interfaces volume of 
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IEEE Std. 1003.1-200x called using dest_file as the path argument. If this attempt 
succeeds, cp shall continue with step 3b. 

b. If dest_file does not exist, a file descriptor shall be obtained by performing actions 
equivalent to the open() function defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x called using dest_file as the path argument, and the bitwise- 
inclusive OR of 0_WRONLY and 0_CREAT as the oflag argument. The file 
permission bits of source_file shall be the mode argument. 

c. If the attempt to obtain a file descriptor fails, cp shall write a diagnostic message to 
standard error, do nothing more with sourceJile, and go on to any remaining files. 

d. The contents of source_file shall be written to the file descriptor. Any write errors 
shall cause cp to write a diagnostic message to standard error and continue to step 3e. 

e. The file descriptor shall be closed. 

f. The cp utility shall do nothing more with source_file. If a write error occurred in step 
3d, it is unspecified if cp continues with any remaining files. If no write error 
occurred in step 3d, cp shall go on to any remaining files. 

4. Otherwise, the following steps shall be taken: 

a. If the -r option was specified, the behavior is implementation-dependent. 

b. If the -R option was specified, the following steps shall be taken: 

i. The dest_file shall be created with the same file type as source_file. 

ii. If sourcejile is a file of type FIFO, the file permission bits shall be the same as 
those of source_file, modified by the file creation mask of the user if the -p 
option was not specified. Otherwise, the permissions, owner ID, and group ID 
of destjile are implementation-dependent. 

If this creation fails for any reason, cp shall write a diagnostic message to 
standard error, do nothing more with source Jile, and go on to any remaining 
files. I 

iii. If source_file is a file of type symbolic link, the path name contained in destjile I 

shall be the same as the path name contained in source Jile. I 

If this fails for any reason, cp shall write a diagnostic message to standard error, I 
do nothing more with source Jile, and go on to any remaining files. I 

If the implementation provides additional or alternate access control mechanisms (see the I 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 4.1, File Access I 
Permissions), their effect on copies of files is implementation-dependent. I 

OPTIONS 

The cp utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-f If a file descriptor for a destination file cannot be obtained, as described in step 

3.a.ii., attempt to unlink the destination file and proceed. I 

-H Take actions based on the type and contents of the file referenced by any symbolic I 

link specified as a source_file operand. I 

-i Write a prompt to standard error before copying to any existing destination file. If 

the response from the standard input is affirmative, the copy shall be attempted; 
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11509 

11510 -L 

11511 

11512 


otherwise, it shall not. I 

Take actions based on the type and contents of the file referenced by any symbolic I 
link specified as a sourcejile operand or any symbolic links encountered during I 
traversal of a file hierarchy. I 


11513 Notes to Reviewers I 

11514 This section with side shading will not appear in the final copy. - Ed. I 

11515 A description of the -P option is needed. This is not in the IEEE P1003.2b draft I 

11516 standard. I 

11517 -p Duplicate the following characteristics of each source file in the corresponding I 

11518 destination file: 


11519 

11520 


1. The time of last data modification and time of last access. If this duplication 
fails for any reason, cp shall write a diagnostic message to standard error. 


11521 

11522 


2. The user ID and group ID. If this duplication fails for any reason, it is 
unspecified whether cp writes a diagnostic message to standard error. 


11523 

11524 

11525 

11526 


3. The file permission bits and the S_ISUID and S_ISGID bits. Other, 
implementation-dependent, bits may be duplicated as well. If this 
duplication fails for any reason, cp shall write a diagnostic message to 
standard error. 


11527 If the user ID or the group ID cannot be duplicated, the file permission bits 

11528 S_ISUID and S_ISGID shall be cleared. If these bits are present in the source file but 

11529 are not duplicated in the destination file, it is unspecified whether cp writes a 

11530 diagnostic message to standard error. 

11531 The order in which the preceding characteristics are duplicated is unspecified. The 

11532 dest_file shall not be deleted if these characteristics cannot be preserved. 

11533 -R Copy file hierarchies. 

11534 ob -r Copy file hierarchies. The treatment of special files is implementation-dependent. 

11535 Specifying more than one of the mutually-exclusive options -H, -L, and -P shall not be I 

11536 considered an error. The last option specified shall determine the behavior of the utility. I 


11537 OPERANDS 

11538 The following operands shall be supported: 


11539 

11540 

11541 

11542 


sonrcejile 
target Jile 

target 


A path name of a file to be copied. 

A path name of an existing or nonexistent file, used for the output when a single 
file is copied. 

A path name of a directory to contain the copied files. 


11543 STDIN 

11544 Used to read an input line in response to each prompt specified in the STDERR section. 

11545 Otherwise, the standard input shall not be used. 


11546 INPUT FILES 

11547 The input files specified as operands may be of any file type. 
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11548 ENVIRONMENT VARIABLES 

11549 The following environment variables shall affect the execution of cp: 


11550 

11551 

11552 

11553 

11554 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


11555 

11556 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


11557 

11558 

11559 

11560 


LCjCOLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements used in the extended regular expression defined for 
the yesexpr locale keyword in the LC_MESSAGES category. 


11561 

11562 

11563 

11564 

11565 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes used in the 
extended regular expression defined for the yesexpr locale keyword in the 
LC_MESSAGES category. 


11566 LC_MESSAGES 

11567 Determine the locale for the processing of affirmative responses that should be 

11568 used to affect the format and contents of diagnostic messages written to standard 

11569 error. 


11570 xsi NLSPATEl Determine the location of message catalogs for the processing of LC_MESSAGES. 

11571 ASYNCHRONOUS EVENTS 

11572 Default. 


11573 STDOUT 

11574 Not used. 


11575 STDERR 

11576 A prompt shall be written to standard error under the conditions specified in the DESCRIPTION 

11577 section. The prompt shall contain the destination path name, but its format is otherwise 

11578 unspecified. Otherwise, the standard error shall be used only for diagnostic messages. 

11579 OUTPUT FILES 

11580 The output files may be of any type. 

11581 EXTENDED DESCRIPTION 

11582 None. 


11583 EXIT STATUS 

11584 The following exit values shall be returned: 

11585 0 All files were copied successfully. 

11586 >0 An error occurred. 


11587 CONSEQUENCES OF ERRORS 

11588 If cp is prematurely terminated by a signal or error, files or file hierarchies may be only partially 

11589 copied and files and directories may have incorrect permissions or access and modification 

11590 times. 
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APPLICATION USAGE 

The difference between -R and -r is in the treatment by cp of file types other than regular and 
directory. The original -r flag, for historic reasons, does not handle special files any differently 
from regular files, but always reads the file and copies its contents. This has obvious problems in 
the presence of special file types; for example, character devices, FIFOs, and sockets. The -R 
option is intended to recreate the file hierarchy and the -r option supports historical practice. It 
was anticipated that a future version of this volume of IEEE Std. 1003.1-200x would deprecate 
the -r option, and for that reason, there has been no attempt to fix its behavior with respect to 
FIFOs or other file types where copying the file is clearly wrong. However, some systems 
support -r with the same abilities as the -R defined in this volume of IEEE Std. 1003.1-200x. To 
accommodate them as well as systems that do not, the differences between -r and -R are 
implementation-dependent. Implementations may make them identical. The -r option is now 
marked obsolescent. 

The set-user-ID and set-group-ID bits are explicitly cleared when files are created. This is to 
prevent users from creating programs that are set-user-ID or set-group-ID to them when 
copying files or to make set-user-ID or set-group-ID files accessible to new groups of users. For 
example, if a file is set-user-ID and the copy has a different group ID than the source, a new 
group of users has execute permission to a set-user-ID program than did previously. In 
particular, this is a problem for superusers copying users' trees. 

EXAMPLES 

None. 

RATIONALE 

The -i option exists on BSD systems, giving applications and users a way to avoid accidentally 
removing files when copying. Although the 4.3 BSD version does not prompt if the standard 
input is not a terminal, the standard developers decided that use of -i is a request for interaction, 
so when the destination path exists, the utility takes instructions from whatever responds on 
standard input. 

The exact format of the interactive prompts is unspecified. Only the general nature of the 
contents of prompts are specified because implementations may desire more descriptive 
prompts than those used on historical implementations. Therefore, an application using the -i 
option relies on the system to provide the most suitable dialog directly with the user, based on 
the behavior specified. 

The -p option is historical practice on BSD systems, duplicating the time of last data 
modification and time of last access. This volume of IEEE Std. 1003.1-200x extends it to preserve 
the user and group IDs, as well as the file permissions. This requirement has obvious problems 
in that the directories are almost certainly modified after being copied. This volume of 
IEEE Std. 1003.1-200x requires that the modification times be preserved. The statement that the 
order in which the characteristics are duplicated is unspecified is to permit implementations to 
provide the maximum amount of security for the user. Implementations should take into 
account the obvious security issues involved in setting the owner, group, and mode in the 
wrong order or creating files with an owner, group, or mode different from the final value. 

It is unspecified whether cp writes diagnostic messages when the user and group IDs cannot be 
set due to the widespread practice of users using -p to duplicate some portion of the file 
characteristics, indifferent to the duplication of others. Historic implementations only write 
diagnostic messages on errors other than [EPERM], 

The -r option is historical practice on BSD and BSD-derived systems, copying file hierarchies as 
opposed to single files. This functionality is used heavily in historical applications, and its loss 
would significantly decrease consensus. The -R option was added as a close synonym to the -r 
option, selected for consistency with all other options in this volume of IEEE Std. 1003.1-200x 
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that do recursive directory descent. 

When a failure occurs during the copying of a file hierarchy, cp is required to attempt to copy 
files that are on the same level in the hierarchy or above the file where the failure occurred. It is 
unspecified if cp shall attempt to copy files below the file where the failure occurred (which 
cannot succeed in any case). 

Permissions, owners, and groups of created special file types have been deliberately left as 
implementation-dependent. This is to allow systems to satisfy special requirements (for 
example, allowing users to create character special devices, but requiring them to be owned by a 
certain group). In general, it is strongly suggested that the permissions, owner, and group be the 
same as if the user had run the historical mknod, In, or other utility to create the file. It is also 
probable that additional privileges are required to create block, character, or other 
implementation-dependent special file types. 

Additionally, the -p option explicitly requires that all set-user-ID and set-group-ID permissions 
be discarded if any of the owner or group IDs cannot be set. This is to keep users from 
unintentionally giving away special privilege when copying programs. 

When creating regular files, historical versions of cp use the mode of the source file as modified 
by the file mode creation mask. Other choices would have been to use the mode of the source file 
unmodified by the creation mask or to use the same mode as would be given to a new file 
created by the user (plus the execution bits of the source file) and then modify it by the file mode 
creation mask. In the absence of any strong reason to change historic practice, it was in large part 
retained. 

When creating directories, historical versions of cp use the mode of the source directory, plus 
read, write, and search bits for the owner, as modified by the file mode creation mask. This is 
done so that cp can copy trees where the user has read permission, but the owner does not. A 
side effect is that if the file creation mask denies the owner permissions, cp fails. Also, once the 
copy is done, historical versions of cp set the permissions on the created directory to be the same 
as the source directory, unmodified by the file creation mask. 

This behavior has been modified so that cp is always able to create the contents of the directory, 
regardless of the file creation mask. After the copy is done, the permissions are set to be the same 
as the source directory, as modified by the file creation mask. This latter change from historical 
behavior is to prevent users from accidentally creating directories with permissions beyond 
those they would normally set and for consistency with the behavior of cp in creating files. 

It is not a requirement that cp detect attempts to copy a file to itself; however, implementations 
are strongly encouraged to do so. Historical implementations have detected the attempt in most 
cases. 

There are two methods of copying subtrees in this volume of IEEE Std. 1003.1-200x. The other 
method is described as part of the pax utility (see pax on page 737). Both methods are historical 
practice. The cp utility provides a simpler, more intuitive interface, while pax offers a finer 
granularity of control. Each provides additional functionality to the other; in particular, pax 
maintains the hard-link structure of the hierarchy, while cp does not. It is the intention of the 
standard developers that the results be similar (using appropriate option combinations in both 
utilities). The results are not required to be identical; there seemed insufficient gain to 
applications to balance the difficulty of implementations having to guarantee that the results 
would be exactly identical. 

The wording allowing cp to copy a directory to implementation-dependent file types not 
specified by the System Interfaces volume of IEEE Std. 1003.1-200x is provided so that 
implementations supporting symbolic links are not required to prohibit copying directories to 
symbolic links. Other extensions to the System Interfaces volume of IEEE Std. 1003.1-200x file 
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11688 types may need to use this loophole as well. 

11689 FUTURE DIRECTIONS 

11690 The -r option may be removed; use -R instead. 

11691 SEE ALSO 

11692 mv, find, In, pax 

11693 CHANGE HISTORY 

11694 First released in Issue 2. 

11695 Issue 4 

11696 Aligned with the ISO/IEC 9945-2:1993 standard. 

11697 Issue 6 

11698 The -r option is marked obsolescent. I 

11699 The new options -H, -L, and -P are added to align with the IEEE P1003.2b draft standard. These I 

11700 options affect the processing of symbolic links. I 
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11701 NAME 

11702 crontab — schedule periodic background work 

11703 SYNOPSIS 

11704 up crontab [file] 

11705 crontab [ — e I —1 | —r ] 

11706 

11707 DESCRIPTION 

11708 The crontab utility shall create, replace, or edit a user's crontab entry; a crontab entry is a list of 

11709 commands and the times at which they shall be executed. The new crontab entry can be input by I 

11710 specifying///^ or input from standard input if no file operand is specified, or by using an editor, if 

11711 -e is specified. 

11712 Upon execution of a command from a crontab entry, the implementation shall supply a default 

11713 environment, defining at least the following environment variables: 

11714 HOME A path name of the useds home directory. 

11715 LOGNAME The user's login name. 

11716 PATH A string representing a search path guaranteed to find all of the standard utilities. 

11717 SHELL A path name of the command interpreter. When crontab is invoked as specified by 

11718 this volume of IEEE Std. 1003.1-200x, the value shall be a path name for sh. 

11719 The values of these variables when crontab is invoked as specified by this volume of 

11720 IEEE Std. 1003.1-200x shall not affect the default values provided when the scheduled command 

11721 is run. 

11722 If standard output and standard error are not redirected by commands executed from the 

11723 crontab entry, any generated output or errors shall be mailed, via an implementation-dependent 

11724 method, to the user. 

11725 xsi Users are permitted to use crontab if their names appear in the file /usr/lib/cron/cron.allow. If 

11726 that file does not exist, the file /usr/lib/cron/cron.deny is checked to determine whether the user 

11727 should be denied access to crontab. If neither file exists, only a process with appropriate 

11728 privileges is allowed to submit a job. If only cron.deny exists and is empty, global usage is 

11729 permitted. The cron.allow and cron.deny files consist of one user name per line. 

11730 OPTIONS 

11731 The crontab utility shall conform to the System Interface Definitions volume of I 

11732 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

11733 The following options shall be supported: 

11734 -e Edit a copy of the invoking user's crontab entry, or create an empty entry to edit if 

11735 the crontab entry does not exist. When editing is complete, the entry shall be 

11736 installed as the user's crontab entry. 

11737 -1 (The letter ell.) List the invoking user's crontab entry. 

11738 -r Remove the invoking user's crontab entry. 

11739 OPERANDS 

11740 The following operand shall be supported: 

11741 file The path name of a file that contains specifications, in the format defined in the 

11742 INPUT FILES section, for crontab entries. 
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11743 STDIN 

11744 See the INPUT FILES section. 


11745 INPUT FILES 

11746 In the POSIX locale, the user or application shall ensure that a crontab entry is a text file I 

11747 consisting of lines of six fields each. The fields shall be separated by <blank> characters. The first I 

11748 five fields shall be integer patterns that specify the following: I 


11749 

11750 

11751 

11752 

11753 


1. Minute (0-59) 

2. Hour (0-23) 

3. Day of the month (1-31) 

4. Month of the year (1-12) 

5. Day of the week (0-6 with 0=Sunday) 


11754 Each of these patterns can be either an asterisk (meaning all valid values), an element, or a list of 

11755 elements separated by commas. An element shall be either a number or two numbers separated I 

11756 by a hyphen (meaning an inclusive range). The specification of days can be made by two fields I 

11757 (day of the month and day of the week). If month, day of month, and day of week are all 

11758 asterisks, every day shall be matched. If either the month or day of month is specified as an 

11759 element or list, but the day of week is an asterisk, the month and day of month fields shall 

11760 specify the days that match. If both month and day of month are specified as asterisk, but day of 

11761 week is an element or list, then only the specified days of the week match. Finally, if either the 

11762 month or day of month is specified as an element or list, and the day of week is also specified as 

11763 an element or list, then any day matching either the month and day of month, or the day of 

11764 week, shall be matched. 


11765 The sixth field of a line in a crontab entry is a string that shall be executed by sli at the specified 

11766 times. A percent sign character in this field shall be translated to a <newline> character. Any 

11767 character preceded by a backslash (including the ' %') shall cause that character to be treated 

11768 literally. Only the first line (up to a ' %' or end-of-line) of the command field shall be executed 

11769 by the command interpreter. The other lines shall be made available to the command as 

11770 standard input. 

11771 Blank lines and those whose first non-<blank> character is ' # ' shall be ignored. 

11772 xsi The text files /usr/lib/cron/cron.allow and /usr/lib/cron/cron.deny contain user names, one per 

11773 line, of users who are, respectively, authorized or denied access to the service underlying the 

11774 crontab utility. 

11775 ENVIRONMENT VARIABLES 


11776 

The following environment variables shall affect the execution of crontab: 

11777 

11778 

EDITOR 

Determine the editor to be invoked when the -e option is specified. The default 
editor shall be vi. 

11779 

11780 

11781 

11782 

11783 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

11784 

11785 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

11786 

11787 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
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11788 

11789 

11790 

11791 

11792 

11793 

11794 

11795 

11796 

11797 

11798 

11799 

11800 

11801 

11802 

11803 

11804 

11805 

11806 

11807 

11808 

11809 

11810 
11811 
11812 

11813 

11814 

11815 

11816 

11817 

11818 

11819 

11820 
11821 
11822 

11823 

11824 

11825 

11826 

11827 

11828 


arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

If the -1 option is specified, the crontab entry shall be written to the standard output. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

The user's crontab entry is not submitted, removed, edited, or listed. 

APPLICATION USAGE 

The format of the crontab entry shown here is guaranteed only for the POSIX locale. Other 
cultures may be supported with substantially different interfaces, although implementations are 
encouraged to provide comparable levels of functionality. 

The default settings of the HOME, LOGNAME, PATH, and SHELL variables that are given to the 
scheduled job are not affected by the settings of those variables when crontab is run; as stated, 
they are defaults. The text about "invoked as specified by this volume of IEEE Std. 1003.1-200x" 
means that the implementation may provide extensions that allow these variables to be affected 
at runtime, but that the user has to take explicit action in order to access the extension, such as 
give a new option flag or modify the format of the crontab entry. 

A typical user error is to type only crontab; this causes the system to wait for the new crontab 
entry on standard input. If end-of-file is typed (generally <control>-D), the crontab entry is 
replaced by an empty file. In this case, the user should type the interrupt character, which 
prevents the crontab entry from being replaced. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

1. Clean up core files every weekday morning at 3:15 am: 

15 3 * * 1-5 find $HOME —name core 2>/dev/null | xargs rm —f 

2. Mail a birthday greeting: 
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11829 0 12 14 2 * mailx john%Happy Birthday! %Time for lunch. 

11830 3. As an example of specifying the two types of days: 

11831 0 0 1, 15 * 1 

11832 would run a command on the first and fifteenth of each month, as well as on every 

11833 Monday. To specify days by only one field, the other field should be set to ' *'; for 

11834 example: 

11835 0 0 **1 

11836 would run a command only on Mondays. 

11837 RATIONALE 

11838 All references to a cron daemon and to cron files have been omitted. Although historical 

11839 implementations have used this arrangement, there is no reason to limit future implementations. 

11840 This description of crontab is designed to support only users with normal privileges. The format 

11841 of the input is based on the System V crontab ; however, there is no requirement here that the 

11842 actual system database used by the cron daemon (or a similar mechanism) use this format 

11843 internally. For example, systems derived from BSD are likely to have an additional field 

11844 appended that indicates the user identity to be used when the job is submitted. 

11845 The -e option was adopted from the SVID as a user convenience, although it does not exist in all 

11846 historical implementations. 

11847 FUTURE DIRECTIONS 

11848 None. 

11849 SEE ALSO 

11850 at 

11851 CHANGE HISTORY 

11852 First released in Issue 2. 

11853 Issue 4 

11854 Aligned with the ISO/IEC 9945-2:1993 standard. 

11855 Issue 6 

11856 This utility is now marked as part of the User Portability Utilities option. 

11857 The normative text is reworded to avoid use of the term "must” for application requirements. 
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11858 NAME 

11859 csplit — split files based on context 

11860 SYNOPSIS 

11861 UP csplit [— ks] [—f prefix ] [—n number] file argl . . . argn 

11862 

11863 DESCRIPTION 

11864 The csplit utility shall read the file named by the file operand, write all or part of that file into 

11865 other files as directed by the arg operands, and write the sizes of the files. 

11866 OPTIONS 

11867 The csplit utility shall conform to the System Interface Definitions volume of I 

11868 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

11869 The following options shall be supported: 

11870 -f prefix Name the created files prefix 00, prefix 01, ..., prefixn . The default is xxOO ... xxn . If 

11871 the prefix argument would create a file name exceeding {NAME_MAX} bytes, an 

11872 error shall result, csplit shall exit with a diagnostic message and no files shall be 

11873 created. 

11874 -k Leave previously created files intact. By default, csplit shall remove created files if 

11875 an error occurs. 

11876 -n number Use number decimal digits to form file names for the file pieces. The default shall be 

11877 2. 

11878 -s Suppress the output of file size messages. 

11879 OPERANDS 

11880 The following operands shall be supported: 

11881 file The path name of a text file to be split. It file is , the standard input shall be 

11882 used. 


11883 The operands argl ... argn can be a combination of the following: 


11884 

11885 

11886 

11887 

11888 

11889 

11890 

11891 

11892 

11893 

11894 

11895 

11896 

11897 

11898 

11899 

11900 


/ rexp / [offset] 

A file shall be created using the content of the lines from the current line up to, but 
not including, the line that results from the evaluation of the regular expression 
with offset, if any, applied. The regular expression rexp shall follow the rules for 
basic regular expressions described in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 9.3, Basic Regular Expressions. The application shall 
use the sequence " \ / " to specify a slash character within the rexp . The optional 
offset shall be a positive or negative integer value representing a number of lines. 
A positive integer value can be preceded by ' +'. If the selection of lines from an 
offset expression of this type would create a file with zero lines, or one with greater 
than the number of lines left in the input file, the results are unspecified. After the 
section is created, the current line shall be set to the line that results from the 
evaluation of the regular expression with any offset applied. If the current line is 
the first line in the file and a regular expression operation has not yet been 
performed, the pattern match of rexp shall be applied from the current line to the 
end of the file. Otherwise, the pattern match of rexp shall be applied from the line 
following the current line to the end of the file. 


11901 °/orexp°/o[offset] 

11902 Equivalent to /rexp/[offset], except that no file shall be created for the selected 

11903 section of the input file. The application shall use the sequence "\%" to specify a 
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11904 


percent-sign character within the rexp. 


11905 

11906 

11907 


line_no Create a file from the current line up to (but not including) the line number line_no. 

Lines in the file shall be numbered starting at one. The current line becomes 
line_no. 


11908 

11909 

11910 

11911 


{num) Repeat operand. This operand can follow any of the operands described 

previously. If it follows a rexp type operand, that operand shall be applied man 
more times. If it follows a line_no operand, the file shall be split every line_no lines, 
man times, from that point. 


11912 An error shall be reported if an operand does not reference a line between the current position 

11913 and the end of the file. 


11914 STDIN 

11915 See the INPUT FILES section. 


11916 INPUT FILES 

11917 The input file shall be a text file. 


11918 ENVIRONMENT VARIABLES 

11919 The following environment variables shall affect the execution of csplit: 


11920 

11921 

11922 

11923 

11924 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


11925 

11926 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


11927 

11928 

11929 


LCjCOLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements within regular expressions. 


11930 

11931 

11932 

11933 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes within regular 
expressions. 


11934 LC_MESSAGES 

11935 Determine the locale that should be used to affect the format and contents of 

11936 diagnostic messages written to standard error. 

11937 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


11938 ASYNCHRONOUS EVENTS 

11939 If the -k option is specified, created files shall be retained. Otherwise, the default action occurs. 


11940 STDOUT 

11941 Unless the -s option is used, the standard output shall consist of one line per file created, with a 

11942 format as follows: 


11943 "%d\n", <file size in bytes> 
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11944 STDERR 

11945 Used only for diagnostic messages. 

11946 OUTPUT FILES 

11947 The output files shall contain portions of the original input file; otherwise, unchanged. 

11948 EXTENDED DESCRIPTION 

11949 None. 

11950 EXIT STATUS 

11951 The following exit values shall be returned: 

11952 0 Successful completion. 

11953 >0 An error occurred. 

11954 CONSEQUENCES OF ERRORS 

11955 By default, created files shall be removed if an error occurs. When the -k option is specified, 

11956 created files shall not be removed if an error occurs. 

11957 APPLICATION USAGE 

11958 Application writers should note that this utility need not be provided on systems that do not 

11959 support the User Portability Utilities option. 

11960 EXAMPLES 

11961 1. 

11962 

11963 

11964 

11965 

11966 2. 

11967 

11968 

11969 

11970 3. 

11971 

11972 

11973 

11974 RATIONALE 

11975 The -n option was added to extend the range of file names that could be handled. 

11976 Consideration was given to adding a -a flag to use the alphabetic file name generation used by 

11977 the historical split utility, but the functionality added by the -n option was deemed to make 

11978 alphabetic naming unnecessary. 

11979 FUTURE DIRECTIONS 

11980 None. 

11981 SEE ALSO 

11982 sect, split 


This example creates four files, cobolOO ... cobol03: 

csplit —f cobol file '/procedure division/' /par5./ /parl6./ 

After editing the split files, they can be recombined as follows: 

cat cobol0[0—3] > file 

Note that this example overwrites the original file. 

This example would split the file after the first 99 lines, and every 100 lines thereafter, up 
to 9999 lines; this is because lines in the file are numbered from 1 rather than zero, for 
historical reasons: 

csplit —k file 100 {99} 

Assuming that prog.c follows the C-language coding convention of ending routines with a 
' }' at the beginning of the line, this example creates a file containing each separate C 
routine (up to 21) in prog.c: 

csplit —k prog.c '%main(%' '/"}/+!' {20} 
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11983 

11984 

11985 

11986 

11987 

11988 

11989 

11990 

11991 

11992 

11993 

11994 


CHANGE HISTORY 

First released in Issue 2. 

Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

FUTURE DIRECTIONS section added. 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The APPLICATION USAGE section is added. I 

The description of regular expression operands is changed to align with the IEEE P1003.2b draft I 
standard. I 

The normative text is reworded to avoid use of the term "must” for application requirements. I 
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11995 NAME 

11996 ctags — create a tags file (DEVELOPMENT, FORTRAN) 

11997 SYNOPSIS 

11998 up ctags [—a] [—f tags file] pathname . . . 

11999 ctags — x pathname . . . 

12000 


12001 DESCRIPTION 

12002 The ctags utility shall be provided on systems that support the User Portability Utilities option, 

12003 the Software Development Utilities option, and either or both of the C-Language Development 

12004 Utilities option and FORTRAN Development Utilities option. On other systems, it is optional. 

12005 The ctags utility shall create a tags file or an index of objects from C-language or FORTRAN 

12006 source files specified by the pathname operands. The tags file shall list the locators of language- 

12007 specific objects within the source files. A locator consists of a name, path name, and either a I 

12008 search pattern or a line number that can be used in searching for the object definition. The I 

12009 objects that shall be recognized are specified in the EXTENDED DESCRIPTION section. 


12010 OPTIONS 

12011 The ctags utility shall conform to the System Interface Definitions volume of I 

12012 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

12013 The following options shall be supported: 


12014 -a 


Append to tags file. 


12015 -f tagsfile Write the object locator lists into tagsfile instead of the default file named tags in 

12016 the current directory. 


12017 -X 

12018 
12019 


Produce a list of object names, the line number, and file name in which each is 
defined, as well as the text of that line, and write this to the standard output. A 
tags file shall not be created when -x is specified. 


12020 OPERANDS 

12021 The following pathname operands are supported: 


12022 file.c Files with basenames ending with the .c suffix shall be treated as C-language 

12023 source code. Such files that are not valid input to c89 produce unspecified results. 

12024 file .h Files with basenames ending with the .h suffix shall be treated as C-language 

12025 source code. Such files that are not valid input to c89 produce unspecified results. 


12026 fileS 

12027 

12028 


Files with basenames ending with the .f suffix shall be treated as FORTRAN- 
language source code. Such files that are not valid input to fort77 produce 
unspecified results. 


12029 The handling of other files is implementation-dependent. 


12030 STDIN 

12031 See the INPUT FILES section. 


12032 INPUT FILES 

12033 The input files shall be text files containing source code in the language indicated by the operand I 

12034 file name suffixes. 
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12035 ENVIRONMENT VARIABLES 

12036 The following environment variables shall affect the execution of ctags: 


12037 

12038 

12039 

12040 

12041 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


12042 

12043 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


12044 

12045 

12046 


LCjCOLLATE 

Determine the order in which output is sorted for the -x option. The POSIX locale 
determines the order in which the tags file is written. 


12047 

12048 

12049 

12050 

12051 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). When processing C-language source code, if the locale 
is not compatible with the C locale described by the ISO C standard, the results are 
unspecified. 


12052 LC_MESSAGES 

12053 Determine the locale that should be used to affect the format and contents of 

12054 diagnostic messages written to standard error. 

12055 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


12056 ASYNCHRONOUS EVENTS 

12057 Default. 


12058 STDOUT 

12059 The list of object name information produced by the -x option shall be written to standard 

12060 output in the following format: 

12061 "%s %d %s %s", <object~name>, <line-number>, <filename>, 

12062 <text> 

12063 where <text> is the text of line <line-number> of file <filename>. 

12064 STDERR 

12065 Used only for diagnostic messages. 

12066 OUTPUT FILES 

12067 When the -x option is not specified, the format of the output file shall be: 

12068 "%s\t%s\t/%s/\n" , <identifier>, <filename>, <pattern> 

12069 where <pattern> is a search pattern that could be used by an editor to find the defining instance 

12070 of <identifier> in <filename> (where defining instance is indicated by the declarations listed in the 

12071 EXTENDED DESCRIPTION). 

12072 An optional circumflex (' "') can be added as a prefix to <pattern>, and an optional dollar sign 

12073 can be appended to <pattern> to indicate that the pattern is anchored to the beginning (end) of a 

12074 line of text. Any slash or backslash characters in <pattern> shall be preceded by a backslash 

12075 character. The anchoring circumflex, dollar sign, and escaping backslash characters shall not be 

12076 considered part of the search pattern. All other characters in the search pattern shall be 

12077 considered literal characters. 
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12078 An alternative format is: I 

12079 "%s\t%s\t?%s?\n", <identifier>, <filename>, <pattern> 

12080 which is identical to the first format except that slashes in <pattern> shall not be preceded by I 

12081 escaping backslash characters, and question mark characters in <pattern> shall be preceded by I 

12082 backslash characters. I 

12083 A second alternative format is: I 

12084 "%s\t%s\t%d\n" , <identifier>, <filename>, <lineno> 

12085 where <lineno> is a decimal line number that could be used by an editor to find <identifier> in I 

12086 <filename>. I 

12087 Neither alternative format shall be produced by ctags when it is used as described by I 

12088 IEEE Std. 1003.1-200x, but the standard utilities that process tags files shall be able to process I 

12089 those formats as well as the first format. I 

12090 In any of these formats, the file shall be sorted by identifier, based on the collation sequence in I 

12091 the POSIX locale. I 

12092 EXTENDED DESCRIPTION 

12093 If the operand identifies C-language source, the ctags utility shall attempt to produce an output 

12094 line for each of the following objects: 

12095 • Function definitions 

12096 • Type definitions 

12097 • Macros with arguments 

12098 It may also produce output for any of the following objects: 

12099 • Function prototypes 

12100 • Structures 

12101 • Unions 

12102 • Global variable definitions 

12103 • Enumeration types 

12104 • Macros without arguments 

12105 • #define statements 

12106 • #line statements 

12107 Any #if and #ifdef statements shall produce no output. The tag main is treated specially in C 

12108 programs. The tag formed shall be created by prefixing M to the name of the file, with the 

12109 trailing .c, and leading path name components (if any) removed. 

12110 On systems that do not support the C-Language Development Utilities option, ctags produces 

mil undefined results for C-language source code files. 

12112 If the operand identifies FORTRAN source, the ctags utility shall produce an output line for each 

12113 function definition. It may also produce output for any of the following objects: 

12114 • Subroutine definitions 

12115 • COMMON statements 
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12116 

12117 

12118 

12119 

12120 
12121 

12122 

12123 

12124 

12125 

12126 

12127 

12128 

12129 

12130 

12131 

12132 

12133 

12134 

12135 

12136 

12137 

12138 

12139 

12140 

12141 

12142 

12143 

12144 

12145 

12146 

12147 

12148 

12149 

12150 

12151 

12152 

12153 

12154 

12155 

12156 

12157 

12158 

12159 


• PARAMETER statements 

• DATA and BLOCK DATA statements 

• Statement numbers 

On systems that do not support the FORTRAN Development Utilities option, ctags produces 
unspecified results for FORTRAN source code files. It should write to standard error a message 
identifying this condition and cause a non-zero exit status to be produced. 

It is implementation-dependent what other objects (including duplicate identifiers) produce 
output. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The output with -x is meant to be a simple index that can be written out as an off-line readable 
function index. If the input files to ctags (such as .c files) were not created using the same locales 
as those in effect when ctags -x is run, results might not be as expected. 

The description of C-language processing says "attempts to" because the C language can be 
greatly confused, especially through the use of #defines, and this utility would be of no use if 
the real C preprocessor were run to identify them. The output from ctags may be fooled and 
incorrect for various constructs. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

The option list was significantly reduced from that provided by historical implementations. The 
-F option was omitted as redundant, since it is the default. The -B option was omitted as being 
of very limited usefulness. The -t option was omitted since the recognition of typedefs is now 
required for C source files. The -u option was omitted because the update function was judged 
to be not only inefficient, but also rarely needed. 

An early proposal included a -w option to suppress warning diagnostics. Since the types of such 
diagnostics could not be described, the option was omitted as being not useful. 

The text for LC_CTYPE about compatibility with the C locale acknowledges that the ISO C 
standard imposes requirements on the locale used to process C source. This could easily be a 
superset of that known as "the C locale" by way of implementation extensions, or one of a few 
alternative locales for systems supporting different codesets. No statement is made for 
FORTRAN because the ANSI X3.9-1978 standard (FORTRAN 77) does not (yet) define a similar 
locale concept. However, a general rule in this volume of IEEE Std. 1003.1-200x is that any time 
that locales do not match (preparing a file for one locale and processing it in another), the results 
are suspect. 

The collation sequence of the tags file is not affected by LC_COLLATE because it is typically not 
used by human readers, but only by programs such as vi to locate the tag within the source files. I 
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12160 Using the POSIX locale eliminates some of the problems of coordinating locales between the I 

12161 ctags file creator and the vi file reader. 

12162 Historically, the tags file has been used only by ex and vi. However, the format of the tags file 

12163 has been published to encourage other programs to use the tags in new ways. The format allows 

12164 either BREs or line numbers to find the identifiers because the historical vi recognizes either. The 

12165 ctags utility does not produce the format using line numbers because it is not useful following 

12166 any source file changes that add or delete lines. The documented search patterns match I 

12167 historical practice. It should be noted that literal leading circumflex or trailing dollar-sign I 

12168 characters in the search pattern will only behave correctly if anchored to the beginning of the I 

12169 line or end of the line by an additional circumflex or dollar-sign character. I 

12170 Historical implementations also understand the objects used by the languages Pascal and 

12171 sometimes LISP, and they understand the C source output by lex and yacc. The ctags utility is 

12172 not required to accommodate these languages, although implementors are encouraged to do so. 

12173 The following historical option was not specified, as vgrind is not included in this volume of 

12174 IEEE Std. 1003.1-200x: 

12175 -v If the -v flag is given, an index of the form expected by vgrind is produced on the 

12176 standard output. This listing contains the function name, file name, and page 

12177 number (assuming 64-line pages). Since the output is sorted into lexicographic 

12178 order, it may be desired to run the output through sort -f. Sample use: 

12179 ctags — v files | sort —f > index vgrind —x index 

12180 The special treatment of the tag main makes the use of ctags practical in directories with more 

12181 than one program. 

12182 FUTURE DIRECTIONS 

12183 None. I 

12184 SEE ALSO 

12185 c89,fort77, vi 

12186 CHANGE HISTORY 

12187 First released in Issue 4. 

12188 Issue 5 

12189 FUTURE DIRECTIONS section added. 

12190 Issue 6 

12191 This utility is now marked as part of the User Portability Utilities option. I 

12192 The OUTPUT FILES section is changed to align with the IEEE P1003.2b draft standard. I 

12193 The normative text is reworded to avoid use of the term "must” for application requirements. I 


322 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


cut 


12194 NAME 

12195 cut — cut out selected fields of each line of a file 


12196 SYNOPSIS 

12197 cut —b list [—n] [file ...] 

12198 cut —c list [file ...] 


12199 cut —f list [—d delim ] [—s] [file . . .] 


12200 DESCRIPTION 

12201 The cut utility shall cut out bytes (-b option), characters (-c option) or character-delimited fields 

12202 (-f option) from each line in one or more files, concatenate them, and write them to standard 

12203 output. 


12204 OPTIONS 

12205 The cut utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

12206 Section 12.2, Utility Syntax Guidelines. 

12207 The application shall ensure that the option-argument list (see options -b, -c, and -f below) is a 

12208 comma-separated list or <blank> character-separated list of positive numbers and ranges. 

12209 Ranges can be in three forms. The first is two positive numbers separated by a hyphen 

12210 (low-high ), which represents all fields from the first number to the second number. The second is 

12211 a positive number preceded by a hyphen (-high ), which represents all fields from field number 1 

12212 to that number. The third is a positive number followed by a hyphen (low-), which represents 

12213 that number to the last field, inclusive. The elements in list can be repeated, can overlap, and can 

12214 be specified in any order, but the bytes, characters, or fields selected shall be written in the order 

12215 of the input data. If an element appears in the selection list more than once, it shall be written 

12216 exactly once. 

12217 The following options shall be supported: 


12218 

12219 

12220 
12221 

12222 


-b list Cut based on a list of bytes. Each selected byte shall be output unless the -n option 

is also specified. It shall not be an error to select bytes not present in the input line. 

-c list Cut based on a list of characters. Each selected character shall be output. It shall 

not be an error to select characters not present in the input line. 

-d delim Set the field delimiter to the character delim. The default is the <tab> character. 


12223 

12224 

12225 

12226 
12227 


-f list Cut based on a list of fields, assumed to be separated in the file by a delimiter 

character (see -d). Each selected field shall be output. Output fields shall be 
separated by a single occurrence of the field delimiter character. Lines with no field 
delimiters shall be passed through intact, unless -s is specified. It shall not be an 
error to select fields not present in the input line. 


12228 -n Do not split characters. When specified with the -b option, each element in list of 

12229 the form lozv-high (hyphen-separated numbers) shall be modified as follows: 


12230 

12231 

12232 

12233 

12234 

12235 

12236 


• If the byte selected by lozv is not the first byte of a character, lozv shall be 
decremented to select the first byte of the character originally selected by lozv. 
If the byte selected by high is not the last byte of a character, high shall be 
decremented to select the last byte of the character prior to the character 
originally selected by high, or zero if there is no prior character. If the resulting 
range element has high equal to zero or lozv greater than high, the list element 
shall be dropped from list for that input line without causing an error. 


12237 Each element in list of the form lozv- shall be treated as above with high set to the 

12238 number of bytes in the current line, not including the terminating <newline> 
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12239 

12240 

12241 


character. Each element in list of the form -high shall be treated as above with low 
set to 1. Each element in list of the form num (a single number) shall be treated as 
above with lozv set to man and high set to man. 


12242 -s Suppress lines with no delimiter characters, when used with the -f option. Unless 

12243 specified, lines with no delimiters shall be passed through untouched. 


12244 OPERANDS 

12245 The following operand shall be supported: 


12246 file A path name of an input file. If no file operands are specified, or if a file operand is 

12247 ' , the standard input shall be used. 


12248 STDIN 

12249 The standard input shall be used only if no file operands are specified, or if a file operand is ' . 

12250 See the INPUT FILES section. 


12251 INPUT FILES 

12252 The input files shall be text files, except that line lengths shall be unlimited. 

12253 ENVIRONMENT VARIABLES 


12254 

The following environment variables shall affect the execution of cut: 

12255 

12256 

12257 

12258 

12259 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

12260 

12261 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

12262 

12263 

12264 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

12265 

12266 

12267 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

12268 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


12269 ASYNCHRONOUS EVENTS 

12270 Default. 


12271 STDOUT 

12272 The cut utility output shall be a concatenation of the selected bytes, characters, or fields (one of 

12273 the following): 

12274 "%s\n", <concatenation of bytes> 

12275 "%s\n", <concatenation of characters> 

12276 "%s\n", <concatenation of fields and field delimiters> 

12277 STDERR 

12278 Used only for diagnostic messages. 


324 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


cut 


12279 OUTPUT FILES 

12280 None. 

12281 EXTENDED DESCRIPTION 

12282 None. 

12283 EXIT STATUS 

12284 The following exit values shall be returned: 

12285 0 All input files were output successfully. 

12286 >0 An error occurred. 

12287 CONSEQUENCES OF ERRORS 

12288 Default. 

12289 APPLICATION USAGE 

12290 Earlier versions of the cut utility worked in an environment where bytes and characters were 

12291 considered equivalent (modulo <backspace> and <tab> character processing in some 

12292 implementations). In the extended world of multi-byte characters, the new -b option has been 

12293 added. The -n option (used with -b) allows it to be used to act on bytes rounded to character 

12294 boundaries. The algorithm specified for -n guarantees that: 

12295 cut —b 1—500 —n file > filel 

12296 cut —b 501— —n file > file2 

12297 ends up with all the characters in file appearing exactly once in filel or file2. (There is, 

12298 however, a <newline> character in both filel and file2 for each <newline> character in file.) 

12299 EXAMPLES 

12300 

12301 

12302 

12303 

12304 

12305 

12306 

12307 

12308 

12309 

12310 

12311 

12312 

12313 

12314 

12315 

12316 

12317 

12318 

12319 

12320 


Commands and Utilities, Issue 6 325 


Examples of the option qualifier list: 

1,4,7 Select the first, fourth, and seventh bytes, characters, or fields and field delimiters. 

1-3,8 Equivalent to 1,2,3,8. 

-5,10 Equivalent to 1,2,3,4,5,10. 

3- Equivalent to third to last, inclusive. 

The lozv-high forms are not always equivalent when used with -b and -n and multi-byte 
characters; see the description of -n. 

The following command: 

cut -d : -f 1,6 /etc/passwd 

reads the System V password file (user database) and produces lines of the form: 

<user ID>:<home directory> 

Most utilities in this volume of IEEE Std. 1003.1-200x work on text files. The cut utility can be 
used to turn files with arbitrary line lengths into a set of text files containing the same data. The 
paste utility can be used to create (or recreate) files with arbitrary line lengths. For example, if file 
contains long lines: 

cut —b 1—500 —n file > filel 
cut —b 501— —n file > file2 

creates filel (a text file) with lines no longer than 500 bytes (plus the <newline> character) and 
file2 that contains the remainder of the data from file. (Note that file2 is not a text file if there 
are lines in file that are longer than 500 + {LINE_MAX} bytes.) The original file can be recreated 
from filel and file2 using the command: 
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12321 paste — d "\0" filel file2 > file 

12322 RATIONALE 

12323 Some historical implementations do not count <backspace> characters in determining character 

12324 counts with the -c option. This may be useful for using ait for processing nroff output. It was 

12325 deliberately decided not to have the -c option treat either <backspace> or <tab> characters in 

12326 any special fashion. The fold utility does treat these characters specially. 

12327 Unlike other utilities, some historical implementations of ait exit after not finding an input file, 

12328 rather than continuing to process the remaining file operands. This behavior is prohibited by this 

12329 volume of IEEE Std. 1003.1-200x, where only the exit status is affected by this problem. 

12330 The behavior of ait when provided with either mutually-exclusive options or options that do 

12331 not work logically together has been deliberately left unspecified in favor of global wording in 

12332 Section 1.11 on page 25. 

12333 The OPTIONS section was changed in response to P1003.2-N149. The change represents 

12334 historical practice on all known systems. The original standard was ambiguous on the nature of 

12335 the output. 

12336 The list option-arguments are historically used to select the portions of the line to be written, but 

12337 do not affect the order of the data. For example: 

12338 echo abcdefghi | cut — c6,2,4—7,1 

12339 yields "abdefg". 

12340 A proposal to enhance ait with the following option: 

12341 -o Preserve the selected field order. When this option is specified, each byte, character, or field 

12342 (or ranges of such) shall be written in the order specified by the list option-argument, even if 

12343 this requires multiple outputs of the same bytes, characters, or fields. 

12344 was rejected because this type of enhancement is outside the scope of the IEEE P1003.2b draft 

12345 standard. 

12346 FUTURE DIRECTIONS 

12347 None. 

12348 SEE ALSO 

12349 grep, paste, Section 2.5 on page 43 

12350 CHANGE HISTORY 

12351 First released in Issue 2. 

12352 Issue 4 

12353 Aligned with the ISO/IEC 9945-2:1993 standard. 

12354 Issue 6 

12355 The OPTIONS section is changed to align with the IEEE P1003.2b draft standard. 

12356 The normative text is reworded to avoid use of the term "must” for application requirements. 
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12357 NAME 

12358 cxref — generate a C-language program cross-reference table (DEVELOPMENT) 

12359 SYNOPSIS 


12360 XSI 

cxref [—cs][—o 

file] [—w num] [—D name [=def] ] . . 

, . [—1 dir] . . . 

12361 

[—U name]. 

. . file . . . 



12362 

12363 DESCRIPTION 

12364 The cxref utility shall analyze a collection of C-language files and attempt to build a cross- 

12365 reference table. Information from #define lines is included in the symbol table. A sorted listing 

12366 shall be written to standard output of all symbols (auto, static, and global) in each file separately, 

12367 or with the -c option, in combination. Each symbol contains an asterisk before the declaring 

12368 reference. 


12369 OPTIONS 

12370 The cxref utility shall conform to the System Interface Definitions volume of I 

12371 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that the order of the -D, —I, I 

12372 and -U options (which are identical to their interpretation by c89) is significant. The following 

12373 options shall be supported: 


12374 

12375 

12376 

12377 

12378 


-c Write a combined cross-reference of all input files. 

-w mini Format output no wider than mini (decimal) columns. This option defaults to 80 if 
num is not specified or is less than 51. 

-ofile Direct output to named/i/e. 

-s Operate silently; do not print input file names. 


12379 OPERANDS 

12380 The following operand shall be supported: 


12381 file A path name of a C-language source file. 


12382 STDIN 

12383 Not used. 


12384 INPUT FILES 

12385 The input files are C-language source files. 


12386 ENVIRONMENT VARIABLES 

12387 The following environment variables shall affect the execution of cxref 


12388 

12389 

12390 

12391 

12392 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


12393 LC_ALL If set to a non-empty string value, override the values of all the other 

12394 internationalization variables. 


12395 LCjCOLLATE 

12396 Determine the locale for the ordering of the output. 


12397 

12398 

12399 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 
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12400 

12401 

12402 

12403 

12404 

12405 

12406 

12407 

12408 

12409 

12410 

12411 

12412 

12413 

12414 

12415 

12416 

12417 

12418 

12419 

12420 

12421 

12422 

12423 

12424 

12425 

12426 

12427 

12428 

12429 

12430 

12431 

12432 

12433 

12434 

12435 

12436 

12437 

12438 

12439 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall be used for the cross-reference listing, unless the -o option is used to 
select a different output file. 

The format of standard output is unspecified, except that the following information shall be 
included: 

• If the -c option is not specified, each portion of the listing starts with the name of the input 
file on a separate line. 

• The name line is followed by a sorted list of symbols, each with its associated location path 
name, the name of the function in which it appears (if it is not a function name itself), and 
line number references. 

• Each line number may be preceded by an asterisk (' *') flag, meaning that this is the 
declaring reference. Other single-character flags, with implementation-dependent meanings, 
may be included. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

The output file named by the -o option shall be used instead of standard output. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Application writers should note that this utility need not be provided on systems that do not 
support the XSI Development Utilities option. 

EXAMPLES 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 
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12440 

12441 

12442 

12443 

12444 

12445 

12446 

12447 

12448 

12449 

12450 

12451 


SEE ALSO 

c89 

CHANGE HISTORY 

First released in Issue 2. 

Issue 4 

Format reorganized. 

Utility Syntax Guidelines support mandated. 
Internationalized environment variable support mandated. 

Issue 5 

In the SYNOPSIS, [-U dzr ] zs changed to [-U name]. 

Issue 6 

The APPLICATION USAGE section is added. 
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12452 NAME 

12453 date — write the date and time 

12454 SYNOPSIS 

12455 date [—u] [ + format] 

12456 xsi date [—u] mmddhhmm [ [ cc] yy] 

12457 

12458 DESCRIPTION 

12459 xsi The date utility shall write the date and time to standard output or attempt to set the system date 

12460 and time. By default, the current date and time shall be written. If an operand beginning with 

12461 ' + ' is specified, the output format of date shall be controlled by the field descriptors and other 

12462 text in the operand. 

12463 OPTIONS 

12464 The date utility shall conform to the System Interface Definitions volume of I 

12465 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

12466 The following option shall be supported: 

12467 -u Perform operations as if the TZ environment variable was set to the string "UTCO ", 

12468 or its equivalent historical value of " GMT 0 ". Otherwise, date shall use the 

12469 timezone indicated by the TZ environment variable or the system default if that 

12470 variable is not set. 

12471 OPERANDS 

12472 The following operands shall be supported: 

12473 +format When the format is specified, each field descriptor shall be replaced in the 

12474 standard output by its corresponding value. All other characters shall be copied to 

12475 the output without change. The output always shall be terminated with a 

12476 <newline> character. 


12477 Notes to Reviewers 

12478 This section with side shading will not appear in the final copy. - Ed. 

12479 Dl, XCU, ERN 195 notes that there are differences between the field descriptors 

12480 and the c9X definition for strftime( ). This is included on the issues list. 


12481 

12482 

12483 

12484 

12485 

12486 

12487 

12488 

12489 

12490 

12491 

12492 


Field Descriptors 

%a Locale's abbreviated weekday name. 

%A Locale's full weekday name. 

%b Locale's abbreviated month name. 

%B Locale's full month name. 

%c Locale's appropriate date and time representation. 

%C Century (a year divided by 100 and truncated to an integer) as a decimal 
number [00-99]. 

%d Day of the month as a decimal number [01-31]. 

%D Date in the format mm /dd /yy. 

%e Day of the month as a decimal number [1-31] in a two-digit field with 
leading space character fill. 
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12493 

%h 

A synonym for %b. 

12494 

%H 

Hour (24-hour clock) as a decimal number [00-23]. 

12495 

%I 

Hour (12-hour clock) as a decimal number [01-12]. 

12496 

%j 

Day of the year as a decimal number [001-366]. 

12497 

%m 

Month as a decimal number [01-12]. 

12498 

%M 

Minute as a decimal number [00-59]. 

12499 

%n 

A <newline> character. 

12500 

%p 

Locale's equivalent of either AM or PM. 

12501 

12502 

%r 

12-hour clock time [01-12] using the AM/PM notation; in the POSIX 
locale, this is equivalent to %7:%M:%S% p. 

12503 

%S 

Seconds as a decimal number [00-61]. 

12504 

%f 

A <tab> character. 

12505 

%T 

24-hour clock time [00-23] in the format HH\MM\SS. 

12506 

%u 

Weekday as a decimal number [1 (Monday)-7]. 

12507 

12508 

12509 

%U 

Week of the year (Sunday as the first day of the week) as a decimal 
number [00-53]. All days in a new year preceding the first Sunday shall be 
considered to be in week 0. 

12510 

12511 

12512 

12513 

%V 

Week of the year (Monday as the first day of the week) as a decimal 
number [01-53]. If the week containing January 1 has four or more days in 
the new year, then it shall be considered week 1; otherwise, it shall be the 
last week of the previous year, and the next week shall be week 1. 

12514 

%iv 

Weekday as a decimal number [0 (Sunday)-6]. 

12515 

12516 

12517 

%W 

Week of the year (Monday as the first day of the week) as a decimal 
number [00-53]. All days in a new year preceding the first Monday shall 
be considered to be in week 0. 

12518 

°/oX 

Locale's appropriate date representation. 

12519 

%x 

Locale's appropriate time representation. 

12520 

%y 

Year within century [00-99]. 

12521 

%y 

Year with century as a decimal number. 

12522 

%z 

Timezone name, or no characters if no timezone is determinable. 

12523 

"6 "6 

A percent sign character. 

12524 

12525 

See the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 7.3.5, 
LC_TIME for the field descriptor values in the POSIX locale. 
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12526 

12527 

12528 

12529 

12530 

12531 

12532 

12533 

12534 

12535 

12536 

12537 

12538 

12539 

12540 

12541 

12542 

12543 

12544 

12545 

12546 

12547 

12548 

12549 

12550 

12551 

12552 

12553 

12554 

12555 

12556 

12557 

12558 

12559 

12560 

12561 

12562 

12563 

12564 

12565 

12566 

12567 


date Utilities 


Modified Field Descriptors 

Some field descriptors can be modified by the £ and O modifier characters to 
indicate a different format or specification as specified in the LC_TIME locale 
description (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Section 7.3.5, LC_TIME). If the corresponding keyword (see era, era_year, 
era_d_fmt, and alt_digits in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 7.3.5, LC_TIME) is not specified or not supported for 
the current locale, the unmodified field descriptor value shall be used. 

%Ec Locale's alternative appropriate date and time representation. 

%EC The name of the base year (period) in the locale's alternative 
representation. 

%Ex Locale's alternative date representation. 

%EX Locale's alternative time representation. 

%Ey Offset from %EC (year only) in the locale's alternative representation. 

%EY Full alternative year representation. 

%Od Day of month using the locale's alternative numeric symbols. 

%Oe Day of month using the locale's alternative numeric symbols. 

%OH Hour (24-hour clock) using the locale's alternative numeric symbols. 

%OI Hour (12-hour clock) using the locale's alternative numeric symbols. 

%Om Month using the locale's alternative numeric symbols. 

%OM Minutes using the locale's alternative numeric symbols. 

%OS Seconds using the locale's alternative numeric symbols. 

%Ou Weekday as a number in the locale's alternative representation (Monday 
= 1 ). 

%OU Week number of the year (Sunday as the first day of the week) using the 
locale's alternative numeric symbols. 

%OV Week number of the year (Monday as the first day of the week, rules 
corresponding to %V), using the locale's alternative numeric symbols. 

%Oiv Weekday as a number in the locale's alternative representation (Sunday = 

0 ). 

%OW Week number of the year (Monday as the first day of the week) using the 
locale's alternative numeric symbols. 

%Oxj Year (offset from %C) in alternative representation. 

xsi mmddhhmm[[cc\yy ] 

Attempt to set the system date and time from the value given in the operand. This 
is only possible if the user has appropriate privileges and the system permits the 
setting of the system date and time. The first mm is the month (number); dd is the 
day (number); hh is the hour (number, 24-hour system); the second mm is the 
minute (number); cc is the century and is the first two digits of the year (this is 
optional); yy is the last two digits of the year and is optional. If century is not 
specified, then values in the range [69-99] shall refer to years 1969 to 1999 
inclusive, and values in the range [00-68] shall refer to years 2000 to 2068 inclusive. 
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12568 STDIN 

12569 Not used. 

12570 INPUT FILES 

12571 None. 


12572 ENVIRONMENT VARIABLES 

12573 The following environment variables shall affect the execution of date: 


12574 

12575 

12576 

12577 

12578 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


12579 

12580 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


12581 

12582 

12583 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


12584 LC_MESSAGES 

12585 Determine the locale that should be used to affect the format and contents of 

12586 diagnostic messages written to standard error. 

12587 LC_TIME Determine the format and contents of date and time strings written by date. 

12588 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

12589 TZ Determine the timezone in which the time and date are written, unless the -u 

12590 option is specified. If the TZ variable is not set and the -u is not specified, an 

12591 unspecified system default timezone is used. 


12592 ASYNCHRONOUS EVENTS 

12593 Default. 


12594 STDOUT 

12595 When no formatting operand is specified, the output in the POSIX locale shall be equivalent to 

12596 specifying: 

12597 date "+%a %b %e %H:%M:%S %Z %Y" 


12598 STDERR 

12599 Used only for diagnostic messages. 

12600 OUTPUT FILES 

12601 None. 


12602 EXTENDED DESCRIPTION 

12603 None. 


12604 EXIT STATUS 

12605 The following exit values shall be returned: 

12606 0 The date was written successfully. 

12607 >0 An error occurred. 
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12608 CONSEQUENCES OF ERRORS 

12609 Default. 

12610 APPLICATION USAGE 

12611 Field descriptors are of unspecified format when not in the POSIX locale. Some of them can 

12612 contain <newline> characters in some locales, so it may be difficult to use the format shown in 

12613 standard output for parsing the output of date in those locales. 

12614 The range of values for %S extends from 0 to 61 seconds to accommodate the occasional leap 

12615 second or double leap second. 

12616 Although certain of the field descriptors in the POSIX locale (such as the name of the month) are 

12617 shown with initial capital letters, this need not be the case in other locales. Programs using these 

12618 fields may need to adjust the capitalization if the output is going to be used at the beginning of a 

12619 sentence. 

12620 The date string formatting capabilities are intended for use in Gregorian-style calendars, 

12621 possibly with a different starting year (or years). The %x and %c field descriptors, however, are 

12622 intended for local representation; these may be based on a different, non-Gregorian calendar. 

12623 The %C field descriptor was introduced to allow a fallback for the %EC (alternative year format 

12624 base year); it can be viewed as the base of the current subdivision in the Gregorian calendar. A 

12625 century is not calculated as an ordinal number; this Guide was published in century 19, not the 

12626 twentieth. Both the %Ey and %y can then be viewed as the offset from %EC and %C, 

12627 respectively. 

12628 The E and O modifiers modify the traditional field descriptors, so that they can always be used, 

12629 even if the implementation (or the current locale) does not support the modifier. 

12630 The £ modifier supports alternative date formats, such as the Japanese Emperor's Era, as long as 

12631 these are based on the Gregorian calendar system. Extending the E modifiers to other date 

12632 elements may provide an implementation-dependent extension capable of supporting other 

12633 calendar systems, especially in combination with the O modifier. 

12634 The O modifier supports time and date formats using the locale's alternative numerical symbols, 

12635 such as Kanji or Hindi digits or ordinal number representation. 

12636 Non-European locales, whether they use Latin digits in computational items or not, often have 

12637 local forms of the digits for use in date formats. This is not totally unknown even in Europe; a 

12638 variant of dates uses Roman numerals for the months: the third day of September 1991 would be 

12639 written as 3.IX.1991. In Japan, Kanji digits are regularly used for dates; in Arabic-speaking 

12640 countries, Hindi digits are used. The %d, %e, %H, %I, %m, %S, %U, %w, %W, and %y field 

12641 descriptors always return the date and time field in Latin digits (that is, 0 to 9). The %0 modifier 

12642 was introduced to support the use for display purposes of non-Latin digits. In the LC_TIME 

12643 category in localedef, the optional alt_digits keyword is intended for this purpose. As an 

12644 example, assume the following (partial) localedef source: 

12645 alt_digits "I"; "II"; "III"; "IV"; "V"; "VI"; "VII"; "VIII" \ 

12646 "IX"; "X"; "XI"; "XII" 

12647 d_fmt " %e . %Om. %Y " 

12648 With the above date, the command: 

12649 date "+%x" 

12650 would yield 3.IX.1991. With the same d_fmt, but without the alt_digits, the command would 

12651 yield 3.9.1991. 
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12652 EXAMPLES 


12653 

12654 

1. 

The following are input/output examples of date used at arbitrary times in the POSIX 
locale: 

12655 

12656 


$ date 

Tue Jun 26 09:58:10 PDT 1990 

12657 

12658 

12659 


$ date " +DATE : %m/%d/%y%nTIME : %H:%M:%S" 

DATE: 11/02/91 

TIME: 13:36:16 

12660 

12661 


$ date " +TIME: %r" 

TIME: 01:36:32 PM 

12662 

2. 

Examples for Denmark, where the default date and time format is %a %d %b %Y %T %Z: 

12663 

12664 


$ LANG=da_DK.iso_8859—1 date 

ons 02 okt 1991 15:03:32 CET 

12665 

12666 

12667 


$ LANG=da_DK.iso_8859—1 date "+DATO: %A den %e. %B nKLOKKEN : %H:%M:' 

DATO: onsdag den 2. oktober 1991 

KLOKKEN: 15:03:56 

12668 

3. 

Examples for Germany, where the default date and time format is %fl %d.%/z.%Y, %T %Z: 

12669 

12670 


$ LANG=De_DE.88591 date 

Mi 02.Okt.1991, 15:01:21 MEZ 

12671 

12672 

12673 


$ LANG=De_DE.88591 date " +DATUM : %A, %d. %B nZEIT : %H:%M:%S" 

DATUM: Mittwoch, 02. Oktober 1991 

ZEIT: 15:02:02 

12674 

4. 

Examples for France, where the default date and time format is %a %d %h %Y %Z %T: 

12675 

12676 


$ LANG=Fr_FR.88591 date 

Mer 02 oct 1991 MET 15:03:32 

12677 

12678 

12679 


$ LANG=Fr_FR.88591 date "+ JOUR : %A %d %B nHEURE : %H:%M:%S" 

JOUR: Mercredi 02 octobre 1991 

HEURE: 15:03:56 

12680 RATIONALE 



12681 

12682 

12683 

12684 

12685 

12686 

12687 

12688 

12689 

12690 

12691 

12692 

12693 

12694 

12695 
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Some of the new options for formatting are from the ISO C standard. The -u option was 
introduced to allow portable access to Coordinated Universal Time (UTC). The string " GMT0 " is 
allowed as an equivalent TZ value to be compatible with all of the systems using the BSD 
implementation, where this option originated. 

The %e format field descriptor (adopted from System V) was added because the ISO C standard 
descriptors did not provide any way to produce the historical default date output during the first 
nine days of any month. 

There are two varieties of day and week numbering supported (in addition to any others created 
with the locale-dependent %E and %0 modifier characters): 

• The historical variety in which Sunday is the first day of the week and the weekdays 
preceding the first Sunday of the year are considered week 0. These are represented by %iv 
and %U. A variant of this is %W, using Monday as the first day of the week, but still referring 
to week 0. This view of the calendar was retained because so many historical applications 
depend on it and the ISO C standard strftime () function, on which many date 
implementations are based, was defined in this way. 
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12696 • The international standard, based on the ISO 8601:1988 standard where Monday is the first 

12697 weekday and the algorithm for the first week number is more complex: If the week (Monday 

12698 to Sunday) containing January 1 has four or more days in the new year, then it is week 1; 

12699 otherwise, it is week 53 of the previous year, and the next week is week 1. These are 

12700 represented by the new field descriptors %w and %V, added as a result of international 

12701 comments. 

12702 The %C field descriptor was introduced to allow a fallback for the %EC (alternate year format 

12703 base year); it can be viewed as the base of the current subdivision in the Gregorian calendar. A 

12704 century is not calculated as an ordinal number. The original version of this volume of 

12705 IEEE Std. 1003.1-200x was approved in century 19, not the twentieth. Both the %Ey and %y can 

12706 then be viewed as the offset from %EC and %C, respectively. 

12707 FUTURE DIRECTIONS 

12708 None. 

12709 SEE ALSO 

12710 The System Interfaces volume of IEEE Std. 1003.1-200x, ctime (), printf{) 

12711 CHANGE HISTORY 

12712 First released in Issue 2. 

12713 Issue 4 

12714 Aligned with the ISO/IEC 9945-2:1993 standard. 

12715 Issue 5 

12716 Changes are made for Year 2000 alignment. 

12717 Issue 6 

12718 The following new requirements on POSIX implementations derive from alignment with the 

12719 Single UNIX Specification: 

12720 • The setting of system date and time is described, including how to interpret two-digit year 

12721 values if a century is not given. 

12722 • The %EX modified field descriptor is added. 
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12723 NAME 

12724 dd — convert and copy a file 

12725 SYNOPSIS 

12726 dd [operand . . .] 


12727 DESCRIPTION 

12728 The dd utility shall copy the specified input file to the specified output file with possible 

12729 conversions using specific input and output block sizes. It shall read the input one block at a 

12730 time, using the specified input block size; it shall then process the block of data actually 

12731 returned, which could be smaller than the requested block size. It shall apply any conversions 

12732 that have been specified and write the resulting data to the output in blocks of the specified 

12733 output block size. If the bs =expr operand is specified and no conversions other than sync, 

12734 noerror, or notrunc are requested, the data returned from each input block shall be written as a 

12735 separate output block; if the read returns less than a full block and the sync conversion is not 

12736 specified, the resulting output block shall be the same size as the input block. If the bs =expr 

12737 operand is not specified, or a conversion other than sync, noerror, or notrunc is requested, the 

12738 input shall be processed and collected into full-sized output blocks until the end of the input is 

12739 reached. 


12740 The processing order shall be as follows: 


12741 

12742 

12743 

12744 

12745 

12746 


1. An input block is read. 

2. If the input block is shorter than the specified input block size and the sync conversion is 
specified, null bytes shall be appended to the input data up to the specified size. (If either 
block or unblock is also specified, <space> characters shall be appended instead of null 
bytes.) The remaining conversions and output shall include the pad characters as if they 
had been read from the input. 


12747 

12748 

12749 


3. If the bs=expr operand is specified and no conversion other than sync or noerror is 
requested, the resulting data shall be written to the output as a single block, and the 
remaining steps are omitted. 


12750 

12751 

12752 


4. If the swab conversion is specified, each pair of input data bytes shall be swapped. If there 
is an odd number of bytes in the input block, the last byte in the input record shall not be I 
swapped. I 


12753 

12754 

12755 


5. Any remaining conversions (block, unblock, lease, and ucase) shall be performed. These 
conversions shall operate on the input data independently of the input blocking; an input 
or output fixed-length record may span block boundaries. 


12756 

12757 

12758 

12759 


6. The data resulting from input or conversion or both shall be aggregated into output blocks 
of the specified size. After the end of input is reached, any remaining output shall be 
written as a block without padding if conv=sync is not specified; thus, the final output 
block may be shorter than the output block size. 


12760 OPTIONS 

12761 None. 


12762 OPERANDS 

12763 All of the operands shall be processed before any input is read. The following operands shall be 

12764 supported: 


12765 


\i=file Specify the input path name; the default is standard input. 


12766 

12767 

12768 


oi=file Specify the output path name; the default is standard output. If the seek =expr 

conversion is not also specified, the output file shall be truncated before the copy 
begins, unless conv=notrunc is specified. If seek=expr is specified, but 


Commands and Utilities, Issue 6 


337 



dd 


Utilities 


12769 

12770 

12771 

12772 


conv=notrunc is not, the effect of the copy shall be to preserve the blocks in the 
output file over which dd seeks, but no other portion of the output file shall be 
preserved. (If the size of the seek plus the size of the input file is less than the 
previous size of the output file, the output file shall be shortened by the copy.) 


12773 


ibs =expr Specify the input block size, in bytes, by expr (default is 512). 


12774 


obs =expr Specify the output block size, in bytes, by expr (default is 512). 


12775 

12776 

12777 


bs =expr Set both input and output block sizes to expr bytes, superseding ibs= and obs=. If 

no conversion other than sync, noerror, and notrunc is specified, each input block 
shall be copied to the output as a single block without aggregating short blocks. 


12778 

12779 

12780 


cbs =expr Specify the conversion block size for block and unblock in bytes by expr (default is 

zero). If cbs= is omitted or given a value of zero, using block or unblock produces 
unspecified results. 


12781 XSI 

12782 

12783 

12784 

12785 

12786 

12787 


The application shall ensure that this operand is also specified if the conv= 
operand is specified with a value of ascii, ebcdic, or ibm. For a conv= operand 
with an ascii value, the input is handled as described for the unblock value, except 
that characters are converted to ASCII before any trailing <space> characters are 
deleted. For conv= operands with ebcdic or ibm values, the input is handled as 
described for the block value except that the characters are converted to EBCDIC 
or IBM EBCDIC, respectively, after any trailing <space> characters are added. 


12788 

12789 

12790 


skip=/i Skip n input blocks (using the specified input block size) before starting to copy. 

On seekable files, the implementation shall read the blocks or seek past them; on 
non-seekable files, the blocks shall be read and the data shall be discarded. 


12791 

12792 

12793 

12794 

12795 


seek-// Skip n blocks (using the specified output block size) from beginning of the output 

file before copying. On non-seekable files, existing blocks shall be read and space 
from the current end-of-file to the specified offset, if any, filled with null bytes; on 
seekable files, the implementation shall seek to the specified offset or read the 
blocks as described for non-seekable files. 


12796 

12797 

12798 

12799 XSI 

12800 XSI 

12801 XSI 


count=/i Copy only n input blocks. 
conv-vahie[,value ...] 

Where values are comma-separated symbols from the following list: 

ascii Convert EBCDIC to ASCII; see Table 4-6 on page 340. 

ebcdic Convert ASCII to EBCDIC; see Table 4-6 on page 340. 

ibm Convert ASCII to a different EBCDIC set; see Table 4-7 on page 340. 


12802 


The ascii, ebcdic, and ibm values are mutually-exclusive. 


12803 

12804 

12805 

12806 

12807 

12808 

12809 

12810 
12811 
12812 


block Treat the input as a sequence of <newline> character-terminated or 

end-of-file-terminated variable-length records independent of the 
input block boundaries. Each record shall be converted to a record 
with a fixed length specified by the conversion block size. Any 
<newline> character shall be removed from the input line; <space> 
characters shall be appended to lines that are shorter than their 
conversion block size to fill the block. Lines that are longer than the 
conversion block size shall be truncated to the largest number of 
characters that fit into that size; the number of truncated lines shall 
be reported (see the STDERR section). 
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12815 

12816 

12817 

12818 

12819 

12820 
12821 

12822 

12823 

12824 

12825 

12826 

12827 

12828 

12829 

12830 

12831 

12832 

12833 

12834 

12835 

12836 

12837 

12838 

12839 

12840 

12841 

12842 

12843 

12844 

12845 

12846 

12847 

12848 

12849 

12850 

12851 

12852 

12853 

12854 

12855 

12856 
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The block and unblock values are mutually-exclusive. 

unblock Convert fixed-length records to variable length. Read a number of 
bytes equal to the conversion block size (or the number of bytes 
remaining in the input, if less than the conversion block size), delete 
all trailing <space> characters, and append a <newline> character. 

lease Map uppercase characters specified by the LCjCTYPE keyword 

tolower to the corresponding lowercase character. Characters for 
which no mapping is specified shall not be modified by this 
conversion. 

The lease and ucase symbols are mutually-exclusive. 

ucase Map lowercase characters specified by the LC_CTYPE keyword 

toupper to the corresponding uppercase character. Characters for 
which no mapping is specified shall not be modified by this 
conversion. 


swab Swap every pair of input bytes. I 

no error Do not stop processing on an input error. When an input error 

occurs, a diagnostic message shall be written on standard error, 
followed by the current input and output block counts in the same 
format as used at completion (see the STDERR section). If the sync 
conversion is specified, the missing input shall be replaced with null 
bytes and processed normally; otherwise, the input block shall be 
omitted from the output. 

notrunc Do not truncate the output file. Preserve blocks in the output file not 
explicitly written by this invocation of the dd utility. (See also the 
preceding of =file operand.) 

sync Pad every input block to the size of the ibs= buffer, appending null 

bytes. (If either block or unblock is also specified, append <space> 
characters, rather than null bytes.) 

The behavior is unspecified if operands other than conv= are specified more than once. 

For the bs=, cbs=, ibs=, and obs= operands, the application shall supply an expression I 
specifying a size in bytes. The expression, expr, can be: I 

1. A positive decimal number 

2. A positive decimal number followed by k, specifying multiplication by 1024 

3. A positive decimal number followed by b, specifying multiplication by 512 

4. Two or more positive decimal numbers (with or without k or b) separated by x, specifying 
the product of the indicated values 

All of the operands are processed before any input is read. 

The following two tables display the octal number character values used for the ascii and ebcdic 
conversions (first table) and for the ibm conversion (second table). In both tables, the ASCII 
values are the row and column headers and the EBCDIC values are found at their intersections. 
For example, ASCII 0012 (LF) is the second row, third column, yielding 0045 in EBCDIC. The 
inverted tables (for EBCDIC to ASCII conversion) are not shown, but are in one-to-one 
correspondence with these tables. The differences between the two tables are highlighted by 
small boxes drawn around five entries. 
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12857 Notes to Reviewers 

12858 This section with side shading will not appear in the final copy. - Ed. 

12859 The following 2 tables are commented out of this draft to make document handling easier 

12860 (ability to print 2-up). There are no changes to them. These diagrams are available from the 

12861 Austin Group web site as a separate PDF file. 

12862 Table 4-6 ASCII to EBCDIC Conversion 


12863 


Table 4-7 ASCII to IBM EBCDIC Conversion 


12864 STDIN 

12865 If no if= operand is specified, the standard input shall be used. See the INPUT FILES section. 

12866 INPUT FILES 

12867 The input file can be any file type. 


12868 ENVIRONMENT VARIABLES 

12869 The following environment variables shall affect the execution of dd: 


12870 

12871 

12872 

12873 

12874 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


12875 

12876 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


12877 

12878 

12879 

12880 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the classification of characters as uppercase or 
lowercase, and the mapping of characters from one case to the other. 


12881 LCJAESSAGLS 

12882 Determine the locale that should be used to affect the format and contents of 

12883 diagnostic messages written to standard error and informative messages written to 

12884 standard output. 

12885 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


12886 ASYNCHRONOUS EVENTS 

12887 For SIGINT, the dd utility shall interrupt its current processing, write status information to 

12888 standard error, and exit as though terminated by SIGINT. It shall take the standard action for all 

12889 other signals; see the ASYNCHRONOUS EVENTS section in Section 1.11 on page 25. 


12890 STDOUT 

12891 If no of= operand is specified, the standard output shall be used. The nature of the output 

12892 depends on the operands selected. 


12893 STDERR 

12894 On completion, dd shall write the number of input and output blocks to standard error. In the 

12895 POSIX locale the following formats shall be used: 

12896 "%u+%u records in\n", <number of whole input blocks>, 

12897 <number of partial input blocks> 


12898 "%u+%u records out\n", <number of whole output blocks>, 

12899 <number of partial output blocks> 
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A partial input block is one for which read() returned less than the input block size. A partial 
output block is one that was written with fewer bytes than specified by the output block size. 

In addition, when there is at least one truncated block, the number of truncated blocks shall be 
written to standard error. In the POSIX locale, the format shall be: 

"%u truncated %s\n", <number of truncated blocks>, "record" (if 
<number of truncated blocks> is one) "records" (otherwise) 

Diagnostic messages may also be written to standard error. 

OUTPUT FILES 

If the of= operand is used, the output shall be the same as described in the STDOUT section. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The input file was copied successfully. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If an input error is detected and the no error conversion has not been specified, any partial 
output block shall be written to the output file, a diagnostic message shall be written, and the 
copy operation shall be discontinued. If some other error is detected, a diagnostic message shall 
be written and the copy operation shall be discontinued. 

APPLICATION USAGE 

The input and output block size can be specified to take advantage of raw physical I/O. 

There are many different versions of the EBCDIC codesets. The ASCII and EBCDIC conversions 
specified for the dd utility perform conversions for the version specified by the tables. 

EXAMPLES 

The following command: 

dd if=/dev/rmt0h of=/dev/rmtlh 

copies from tape drive 0 to tape drive 1, using a common historical device naming convention. 

The following command: 

dd ibs=10 skip=l 

strips the first 10 bytes from standard input. 

This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card images per block into the 
ASCII file x: 

dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lease 

RATIONALE 

The OPTIONS section is listed as "None" because there are no options recognized by historical 
dd utilities. Certainly, many of the operands could have been designed to use the Utility Syntax 
Guidelines, which would have resulted in the classic hyphenated option letters. In this version 
of this volume of IEEE Std. 1003.1-200x, dd retains its curious JCL-like syntax due to the large 
number of applications that depend on the historical implementation. 

A suggested implementation technique for conv=noerror,sync is to zero (or <space>-fill, if 
blocking or unblocking) the input buffer before each read and to write the contents of the input 
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buffer to the output even after an error. In this manner, any data transferred to the input buffer 
before the error was detected is preserved. Another point is that a failed read on a regular file or 
a disk generally does not increment the file offset, and dd must then seek past the block on which 
the error occurred; otherwise, the input error occurs repetitively. When the input is a magnetic 
tape, however, the tape normally has passed the block containing the error when the error is 
reported, and thus no seek is necessary. 

The default ibs= and obs= sizes are specified as 512 bytes because there are historical (largely 
portable) scripts that assume these values. If they were left unspecified, unusual results could 
occur if an implementation chose an odd block size. 

Historical implementations of dd used creat() when processing of =file. This makes the seek= 
operand unusable except on special files. The conv=notrunc feature was added because more 
recent BSD-based implementations use open() (without 0_TRUNC) instead of creat(), but they 
fail to delete output file contents after the data copied. 

The zv multiplier (historically meaning zvord), is used in System V to mean 2 and in 4.2 BSD to 
mean 4. Since zvord is inherently non-portable, its use is not supported by this volume of 
IEEE Std. 1003.1-200x. 

Standard EBCDIC does not have the characters ' [' and ' ] ' • The values used in the table are 
taken from a common print train that does contain them. Other than those characters, the print 
train values are not filled in, but appear to provide some of the motivation for the historical 
choice of translations reflected here. 

The Standard EBCDIC table provides a 1:1 translation for all 256 bytes. 

The IBM EBCDIC table does not provide such a translation. The marked cells in the tables differ 
in such a way that: 

1. EBCDIC 0112 (' t') and 0152 (broken pipe) do not appear in the table. 

2. EBCDIC 0137 (' —i') translates to/from ASCII 0236 ('"')• the standard table, EBCDIC 
0232 (no graphic) is used. 

3. EBCDIC 0241 (' ~') translates to/from ASCII 0176 ('"'). tn the standard table, EBCDIC 
0137 ('-i') is used. 

4. 0255 (' [') and 0275 (' ] ') appear twice, once in the same place as for the standard table 
and once in place of 0112 ('<:') and 0241 (' ~'). 

In net result: 

EBCDIC 0275 (' ] ') displaced EBCDIC 0241 (' ~') in cell 0345. 

That displaced EBCDIC 0137 ('-.') in cell 0176. 

That displaced EBCDIC 0232 (no graphic) in cell 0136. 

That replaced EBCDIC 0152 (broken pipe) in cell 0313. 

EBCDIC 0255 (' [') replaced EBCDIC 0112 ('<?'). 

This translation, however, reflects historical practice that (ASCII) and / were often 
mapped to each other, as were ' [' and ' t'; and ' ] ' and (EBCDIC) ' "'. 

The cbs operand is required if any of the ascii, ebcdic, or ibm operands are specified. For the 
ascii operand, the input is handled as described for the unblock operand except that characters 
are converted to ASCII before the trailing <space>s are deleted. For the ebcdic and ibm 
operands, the input is handled as described for the block operand except that the characters are 
converted to EBCDIC or IBM EBCDIC after the trailing <space>s are added. 
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12985 The block and unblock keywords are from historical BSD practice. 

12986 The consistent use of the word record in standard error messages matches most historical 

12987 practice. An earlier version of System V used block, but this has been updated in more recent 

12988 releases. 

12989 Early proposals only allowed two numbers separated by x to be used in a product when 

12990 specifying bs=, cbs=, ibs=, and obs= sizes. This was changed to reflect the historical practice of 

12991 allowing multiple numbers in the product as provided by Version 7 and all releases of System V 

12992 and BSD. I 

12993 A change to the szvab conversion is required to match historical practice and is the result of PASC I 

12994 Interpretation 1003.2-92 #03 and #04, submitted for the ISO POSIX-2:1993 standard. I 

12995 A change to the handling of SIGINT is required to match historical practice and is the result of I 

12996 PASC Interpretation 1003.2-92 #06 submitted for the ISO POSIX-2:1993 standard. I 

12997 FUTURE DIRECTIONS 

12998 None. I 

12999 SEE ALSO 

13000 sed, tr 

13001 CHANGE HISTORY 

13002 First released in Issue 2. 

13003 Issue 4 

13004 Aligned with the ISO/IEC 9945-2:1993 standard. 

13005 Issue 5 

13006 The second paragraph of the cbs= description is reworded and marked EX. 

13007 FUTURE DIRECTIONS section added. I 

13008 Issue 6 I 

13009 Changes are made to sivab conversion and SIGINT handling to align with the IEEE P1003.2b I 

13010 draft standard. I 

13011 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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13012 NAME 

13013 delta — make a delta (change) to an SCCS file (DEVELOPMENT) 

13014 SYNOPSIS 

13015 xsi delta [— nps] [— g list ] [— m mrlist ] [— r SID ] [—y [comment] ] file. . . 

13016 


13017 DESCRIPTION 

13018 The delta utility shall be used to permanently introduce into the named SCCS files changes that 

13019 were made to the files retrieved by get (called the g-files , or generated files). 


13020 OPTIONS 

13021 The delta utility shall conform to the System Interface Definitions volume of I 

13022 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that the -y option has an I 

13023 optional option-argument. This optional option-argument cannot be presented as a separate 

13024 argument. 

13025 The following options shall be supported: 


13026 

13027 

13028 

13029 

13030 


-r SID Uniquely identify which delta is to be made to the SCCS file. The use of this option 

is necessary only if two or more outstanding get commands for editing (get -e) on 
the same SCCS file were done by the same person (login name). The SID value 
specified with the -r option can be either the SID specified on the get command 
line or the SID to be made as reported by the get utility; see get on page 510. 


13031 -s Suppress the report to standard output of the activity associated with each file. 

13032 See the STDOUT section. 


13033 -n 

13034 


Specify retention of the edited g-file (normally removed at completion of delta 
processing). 


13035 

13036 

13037 

13038 

13039 


-g list Specify a list, (see get on page 510 for the definition of list) of deltas that shall be I 

ignored when the file is accessed at the change level (SID) created by this delta. I 

-m mrlist Specify a modification request (MR) number that the application shall supply as I 
the reason for creating the new delta. This is used if the SCCS file has the -v flag I 
set; see admin on page 160. 


13040 

13041 

13042 


If -m is not used and the standard input is a terminal, the prompt described in the 
STDOUT section is written to standard output before the standard input is read; if 
the standard input is not a terminal, no prompt is issued. 


13043 

13044 


MRs in a list are separated by <blank>s. An unescaped <newline> character 
terminates the MR list. 


13045 

13046 

13047 

13048 


Note that if the -v flag has a value, it is taken to be the name of a program which 
validates the correctness of the MR numbers. If a non-zero exit status is returned 
from the MR number validation program, delta terminates. (It is assumed that the 
MR numbers were not all valid.) 


13049 

13050 

13051 

13052 


-y [comment] Describe the reason for making the delta. This is an arbitrary group of lines that 
would meet the definition of a text file. Systems support comments from zero to 512 
bytes and may support longer values. A null string (specified as either -y, —y" ", or 
in response to a prompt for a comment) is considered a valid comment. 


13053 

13054 

13055 

13056 


If -y is not specified and the standard input is a terminal, the prompt described in 
the STDOUT section is written to standard output before the standard input is 
read; if the standard input is not a terminal, no prompt is issued. An unescaped 
<newline> character terminates the comment text. 
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13095 

13096 

13097 

13098 


The -y option is required if the file operand is specified as ' - '. 

-p Write (to standard output) the SCCS file differences before and after the delta is 

applied in diff format; see diff on page 352. 

OPERANDS 

The following operand shall be supported: 

file A path name of an existing SCCS file or a directory. If file is a directory, delta 

behaves as though each file in the directory were specified as a named file, except 
that non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. 

If a single instance file is specified as , the standard input is read; each line of 
the standard input is taken to be the name of an SCCS file to be processed. Non- 
SCCS files and unreadable files are silently ignored. 

STDIN 

The standard input is a text file used only in the following cases: 

• To read an mrlist or a command (see the -m and -y options). 

• A file operand is specified as ' - '. 

INPUT FILES 

Input files are text files whose data is to be included in the SCCS files. If the first character of any 

line of an input file is SOH (binary 001), the results are unspecified. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of delta: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error, and informative messages written 
to standard output. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 

Default. 

STDOUT 

The standard output shall be used only for the following messages in the POSIX locale: 

• Prompts (see the -m and -y options) in the following formats: 

"MRs? " 
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13099 

13100 

13101 

13102 

13103 

13104 

13105 

13106 

13107 

13108 

13109 

13110 

13111 

13112 

13113 

13114 

13115 

13116 

13117 

13118 

13119 

13120 

13121 

13122 

13123 

13124 

13125 

13126 

13127 

13128 

13129 

13130 

13131 

13132 

13133 

13134 

13135 

13136 

13137 


"comments? " 

The MR prompt, if written, always precedes the comments prompt. 

• A report of each file's activities (unless the -s option is specified) in the following format: 

"%s\n%d inserted\n%d deleted\n%d unchanged\n", <New SID>, 

<number of lines inserted >, <number of lines deleted >, 

<number of lines unchanged> 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

Any SCCS files updated are files of an unspecified format. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Application writers should note that this utility need not be provided on systems that do not 
support the XSI Development Utilities option. 

EXAMPLES 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

A version of delta that fully supports the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines may be introduced in a future I 
version. I 

SEE ALSO 

admin , diff, get, prs, rmdel 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Format reorganized. 

Exceptions to Utility Syntax Guidelines conformance noted. 
Internationalized environment variable support mandated. 

Issue 5 

The output format description in the STDOUT section is corrected. 
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13138 Issue 6 

13139 The APPLICATION USAGE section is added. 

13140 The normative text is reworded to avoid use of the term "must” for application requirements. 
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13141 NAME 


df — report free disk space 


13143 SYNOPSIS 

13144 up xsi df [— k ] [—P I — t ] [file. . . ] 


13146 DESCRIPTION 


13147 XSI 


13152 XSI 


The df utility shall write the amount of available space and file slots for file systems on which the 
invoking user has appropriate read access. File systems shall be specified by the file operands; 
when none are specified, information shall be written for all file systems. The format of the 
default output from df is unspecified, but all space figures are reported in 512-byte units, unless 
the -k option is specified. This output shall contain at least the file system names, amount of 
available space on each of these file systems, and the number of free file slots, or inodes, 
available; when -t is specified, the output contains the total allocated space as well. 


13154 OPTIONS 

13155 The df utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

13156 Section 12.2, Utility Syntax Guidelines. 

13157 The following options shall be supported: 

13158 -k Use 1024-byte units, instead of the default 512-byte units, when writing space 

13159 figures. 


13161 xsi 


Produce output in the format described in the STDOUT section. 
Include total allocated-space figures in the output. 


13162 OPERANDS 

13163 The following operand shall be supported: 


13165 XSI 


13169 STDIN 


A path name of a file within the hierarchy of the desired file system. If a file other 
than a FIFO, a regular file, a directory or a special file representing the device 
containing the file system (for example, /dev/dsk/Osl) is specified, the results are 
unspecified. Otherwise, df shall write the amount of free space in the file system 
containing the specified file operand. 


Not used. 


13171 INPUT FILES 

13172 None. 

13173 ENVIRONMENT VARIABLES 

13174 The following environment variables shall affect the execution of df: 


LANG 


LC ALL 


LCjCTYPE 


Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 
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13185 LC_MESSAGES 

13186 Determine the locale that should be used to affect the format and contents of 

13187 diagnostic messages written to standard error and informative messages written to 

13188 standard output. 

13189 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

13190 ASYNCHRONOUS EVENTS 

13191 Default. 


13192 STDOUT 

13193 When both the -k and -P options are specified, the following header line shall be written (in the 

13194 POSIX locale): 

13195 "Filesystem 1024-blocks Used Available Capacity Mounted on\n" 

13196 When the -P option is specified without the -k option, the following header line shall be written 

13197 (in the POSIX locale): 

13198 "Filesystem 512-blocks Used Available Capacity Mounted on\n" 

13199 The implementation may adjust the spacing of the header line and the individual data lines so 

13200 that the information is presented in orderly columns. 

13201 The remaining output with -P shall consist of one line of information for each specified file 

13202 system. These lines shall be formatted as follows: 

13203 "%s %d %d %d %d%% %s\n", <file system namef5>, <total space> , 

13204 <space used>, <space free>, <percentage used>, 

13205 <file system root> 

13206 In the following list, all quantities expressed in 512-byte units (1024-byte when -k is specified) 

13207 shall be rounded up to the next higher unit. The fields are: 

13208 < file system name> 

13209 The name of the file system, in an implementation-dependent format. 

13210 <total space> The total size of the file system in 512-byte units. The exact meaning of this figure 

13211 is implementation-dependent, but should include <space used>, <spacefree>, plus 

13212 any space reserved by the system not normally available to a user. 

13213 <space used> The total amount of space allocated to existing files in the file system, in 512-byte 

13214 units. 


13215 <spacefree> The total amount of space available within the file system for the creation of new 

13216 files by unprivileged users, in 512-byte units. When this figure is less than or equal 

13217 to zero, it shall not be possible to create any new files on the file system without 

13218 first deleting others, unless the process has appropriate privileges. The figure 

13219 written may be less than zero. 

13220 <percentage used> 

13221 The percentage of the normally available space that is currently allocated to all 

13222 files on the file system. This shall be calculated using the fraction: 

13223 <space used>/ ( <space used>+ <space free>) 


13224 expressed as a percentage. This percentage may be greater than 100 if <spacefree> 

13225 is less than zero. The percentage value shall be expressed as a positive integer, 

13226 with any fractional result causing it to be rounded to the next highest integer. 
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<file system root> 

The directory below which the file system hierarchy appears, 
xsi The output format is unspecified when -t is used. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

On most systems, the "name of the file system, in an implementation-dependent format" is the 
special file on which the file system is mounted. 

On large file systems, the calculation specified for percentage used can create huge rounding 
errors. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

1. The following example writes portable information about the /usr file system: 

df —P /usr 

2. Assuming that /usr/src is part of the /usr file system, the following produces the same 
output as the previous example: 

df —P /usr/src 


RATIONALE 

The behavior of d/with the -P option is the default action of the 4.2 BSD df utility. The uppercase 
-P was selected to avoid collision with a known industry extension using -p. 

Historical df implementations vary considerably in their default output. It was therefore 
necessary to describe the default output in a loose manner to accommodate all known historical 
implementations and to add a portable option (-P) to provide information in a portable format. 

The use of 512-byte units is historical practice and maintains compatibility with Is and other 
utilities in this volume of IEEE Std. 1003.1-200x. This does not mandate that the file system itself 
be based on 512-byte blocks. The -k option was added as a compromise measure. It was agreed 
by the standard developers that 512 bytes was the best default unit because of its complete 
historical consistency on System V (versus the mixed 512/1024-byte usage on BSD systems), and 
that a -k option to switch to 1024-byte units was a good compromise. Users who prefer the 
more logical 1 024-byte quantity can easily alias df to df -k without breaking many historical 
scripts relying on the 512-byte units. 
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13269 It was suggested that df and the various related utilities be modified to access a BLOCKSIZE 

13270 environment variable to achieve consistency and user acceptance. Since this is not historical 

13271 practice on any system, it is left as a possible area for system extensions and will be re-evaluated 

13272 in a future version if it is widely implemented. 

13273 FUTURE DIRECTIONS 

13274 None. 

13275 SEE ALSO 

13276 find 

13277 CHANGE HISTORY 

13278 First released in Issue 2. 

13279 Issue 4 

13280 Aligned with the ISO/IEC 9945-2:1993 standard. 

13281 Issue 6 

13282 This utility is now marked as part of the User Portability Utilities option. 
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13283 NAME 

13284 diff — compare two files 

13285 SYNOPSIS 

13286 man diff [—c | —e | —f | —C n ] [—br] filel file2 

13287 DESCRIPTION 

13288 The disutility shall compare the contents of filel and filel and write to standard output a list of 

13289 changes necessary to convert filel into filel. This list should be minimal. No output shall be 

13290 produced if the files are identical. 


13291 OPTIONS 

13292 The diff utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

13293 Section 12.2, Utility Syntax Guidelines. I 

13294 The following options shall be supported: 


13295 -b 

13296 

13297 

13298 


Cause any amount of white space at the end of a line to be treated as a single 
<newline> character (that is, the white-space characters preceding the <newline> 
character are ignored) and other strings of white-space characters, not including 
<newline> characters, to compare equal. 


13299 -C 


Produce output in a form that provides three lines of context. 


13300 

13301 


-C n Produce output in a form that provides n lines of context (where n shall be 

interpreted as a positive decimal integer). 


13302 -e 

13303 


Produce output in a form suitable as input for the ed utility, which can then be 
used to convert filel into filel. 


13304 man -f Produce output in an alternative form, similar in format to -e, but unsuitable as 

13305 input for the ed utility, and in the opposite order. 


13306 -r Apply diff recursively to files and directories of the same name when filel and filel 

13307 are both directories. 


13308 OPERANDS 

13309 The following operands shall be supported: 

13310 filel, filel A path name of a file to be compared. If either the filel or filel operand is ' , the 

13311 standard input shall be used in its place. 

13312 If both filel and filel are directories, diff shall not compare block special files, character special 

13313 files, or FIFO special files to any files and shall not compare regular files to directories. The 

13314 system documentation shall specify the behavior of diff on implementation-dependent file types 

13315 not specified by the System Interfaces volume of IEEE Std. 1003.1-200x when found in 

13316 directories. Further details are as specified in Diff Directory Comparison Format on page 353. 

13317 If only one of filel and filel is a directory, diff shall be applied to the non-directory file and the file 

13318 contained in the directory file with a file name that is the same as the last component of the non- 

13319 directory file. 

13320 STDIN 

13321 The standard input shall be used only if one of the filel or filel operands references standard 

13322 input. See the INPUT FILES section. 

13323 INPUT FILES 

13324 The input files shall be text files. 
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13325 ENVIRONMENT VARIABLES 

13326 The following environment variables shall affect the execution of diff: 


13327 

13328 

13329 

13330 

13331 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


13332 LC_ALL If set to a non-empty string value, override the values of all the other 

13333 internationalization variables. 


13334 

13335 

13336 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


13337 

13338 

13339 

13340 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 


13341 

13342 


LC_TIME Determine the locale for affecting the format of file timestamps written with the 
-C and -c options. 


13343 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

13344 TZ Determine the locale for affecting the timezone used for calculating file 

13345 timestamps written with the -C and -c options. 


13346 ASYNCHRONOUS EVENTS 

13347 Default. 


13348 STDOUT 


13349 Diff Directory Comparison Format 

13350 If both filel and file2 are directories, the following output formats shall be used. 

13351 In the POSIX locale, each file that is present in only one directory shall be reported using the 

13352 following format: 

13353 "Only in %s: %s\n", <directory pathname>, <filename> 

13354 In the POSIX locale, subdirectories that are common to the two directories may be reported with 

13355 the following format: 

13356 "Common subdirectories: %s and %s\n", <directoryl pathname>, 

13357 <directory2 pathname> 

13358 For each file common to the two directories if the two files are not to be compared, the following 

13359 format shall be used in the POSIX locale: 

13360 "File %s is a %s while file %s is a %s\n", <directoryl pathname>, 

13361 <file type of directory 1 pathname>, <directory2 pathname>, 

13362 <file type of directory2 pathname> 

13363 For each file common to the two directories, if the files are compared and are identical, no output 

13364 shall be written. If the two files differ, the following format is written: 

13365 "diff %s %s %s\n", <diff_options>, <filenamel>, <filename2> 


Commands and Utilities, Issue 6 


353 



diff 


Utilities 


13366 

13367 

13368 

13369 

13370 

13371 

13372 

13373 

13374 

13375 

13376 

13377 

13378 

13379 

13380 

13381 

13382 

13383 

13384 

13385 

13386 

13387 

13388 

13389 

13390 

13391 

13392 

13393 

13394 

13395 

13396 

13397 


where <diff_options> are the options as specified on the command line. Depending on these 
options, one of the following output formats shall be used to write the differences. 

All directory path names listed in this section shall be relative to the original command line 
arguments. All other names of files listed in this section are file names (path name components). 

Diff Default Output Format 

man The default (without —e,—f,-c, or -C options) diff utility output shall contain lines of these forms: 

"%da%d\n", <numl>, <num2> 

"%da%d,%d\n" , <numl>, <num2>, <num3> 

"%dd%d\n", <numl>, <num2> 

"%d, %dd%d\n" , <numl>, <num2>, <num3> 

"%dc%d\n", <numl>, <num2> 

"%d,%dc%d\n" , <numl>, <num2>, <num3> 

"%dc%d,%d\n" , <numl>, <num2>, <num3> 

"%d, %dc%d, %d\n" , <numl>, <num2>, <num3> , <num4> 

These lines resemble ed subcommands to convert filet into file2 . The line numbers before the 
action letters shall pertain to filel ; those after shall pertain to file2 . Thus, by exchanging a for d 
and reading the line in reverse order, one can also determine how to convert file! into filel . As in 
ed, identical pairs (where nnml = nit m2) are abbreviated as a single number. 

Following each of these lines, diff shall write to standard output all lines affected in the first file 
using the format: 

"<A%s", <line> 

and all lines affected in the second file using the format: 

">A%s", <line> 

If there are lines affected in both filel and filel (as with the c subcommand), the changes are 
separated with a line consisting of three hyphens: 

"-\n" 

Diff -e Output Format 

With the -e option, a script shall be produced that shall, when provided as input to ed, along 
with an appended w (write) command, convert filel into filel . Only the a (append), c (change), d 
(delete), i (insert), and s (substitute) commands of ed shall be used in this script. Text lines, 
except those consisting of the single character period (' .'), shall be output as they appear in the 
file. 


354 Technical Standard (2000) (Draft February 29, 2000) 





Utilities 


diff 


13398 

13399 MAN 

13400 

13401 

13402 

13403 

13404 

13405 

13406 

13407 

13408 

13409 

13410 

13411 

13412 

13413 

13414 

13415 

13416 

13417 

13418 

13419 

13420 

13421 

13422 

13423 

13424 

13425 

13426 

13427 

13428 

13429 

13430 

13431 

13432 

13433 

13434 

13435 


Diff -f Output Format 

With the -f option, an alternative format of script shall be produced. It is similar to that 
produced by -e, with the following differences: 

1. It is expressed in reverse sequence; the output of -e orders changes from the end of the file 
to the beginning; the -f from beginning to end. 

2. The command form <lines> <command-let ter> used by -e is reversed. For example, 

10c with -e would be clO with -f. 

3. The form used for ranges of line numbers is <space> character-separated, rather than 
comma-separated. 

Diff -c or -C Output Format 

With the -c or -C option, the output format shall consist of affected lines along with 
surrounding lines of context. The affected lines shall show which ones need to be deleted or 
changed in filel, and those added from file!. With the -c option, three lines of context, if 
available, shall be written before and after the affected lines. With the -C option, the user can 
specify how many lines of context are written. The exact format follows. 

The name and last modification time of each file shall be output in the following format: 

"*** %s %s\n", filel, <filel time stamp> 

"-%s %s\n", file2, <file2 time stamp> 

Each <file> field shall be the path name of the corresponding file being compared. The path I 
name written for standard input is unspecified. 

In the POSIX locale, each <timestamp> field shall be equivalent to the output from the following 
command: 

date "+%a %b %e %T %Y" 

without the trailing <newline> character, executed at the time of last modification of the 
corresponding file (or the current time, if the file is standard input). 

Then, the following output formats shall be applied for every set of changes. 

First, a line shall be written in the following format: I 

1 '***************\ n H | 

Next, the range of lines in filel shall be written in the following format: I 

"*** %d,%d ****\n", <beginning line number>, <ending line number> 

Next, the affected lines along with lines of context (unaffected lines) shall be written. Unaffected 
lines shall be written in the following format: 

"AA%s", <unaffected_line> 

Deleted lines shall be written as: 

A%s", <deleted_line> 

Changed lines shall be written as: 

"!A%s", <changed_line> 

Next, the range of lines in file2 shall be written in the following format: 
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13436 

13437 

13438 

13439 

13440 

13441 

13442 

13443 

13444 

13445 

13446 

13447 

13448 

13449 

13450 

13451 

13452 

13453 

13454 

13455 

13456 

13457 

13458 

13459 

13460 

13461 

13462 

13463 

13464 

13465 

13466 

13467 

13468 

13469 

13470 

13471 

13472 

13473 

13474 

13475 

13476 

13477 

13478 

13479 


diff Utilities 


"-%d, %d-\n", <beginning line number>, <ending line number> 

Then, lines of context and changed lines shall be written as described in the previous formats. 
Lines added horn file! shall be written in the following format: 

"+A%s", <added_line> 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 No differences were found. 

1 Differences were found. 

>1 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

If lines at the end of a file are changed and other lines are added, diff output may show this as a 
delete and add, as a change, or as a change and add; diff is not expected to know which 
happened and users should not care about the difference in output as long as it clearly shows the 
differences between the files. 

EXAMPLES 

If dirl is a directory containing a directory named x, dir2 is a directory containing a directory 
named x, dirl/x and dir2/x both contain files named date.out, and dir2/x contains a file named y, 
the command: 

diff —r dirl dir2 

could produce output similar to: 

Common subdirectories: dirl/x and dir2/x 
Only in dir2/x: y 

diff —r dirl/x/date.out dir2/x/date.out 
lcl 

< Mon Jul 2 13:12:16 PDT 1990 

> Tue Jun 19 21:41:39 PDT 1990 

RATIONALE 

The -h option was omitted because it was insufficiently specified and does not add to 
application portability. 

Historical implementations employ algorithms that do not always produce a minimum list of 
differences; the current language about making every effort is the best this volume of 
IEEE Std. 1003.1-200x can do, as there is no metric that could be employed to judge the quality of 
implementations against any and all file contents. The statement "This list should be minimal" 
clearly implies that implementations are not expected to provide the following output when 
comparing two 100-line files that differ in only one character on a single line: 
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1,100cl,100 

all 100 lines from filel preceded with "< " 
all 100 lines from file2 preceded with "> " 

The "Only in" messages required when the -r option is specified are not used by most historical 
implementations if the -e option is also specified. It is required here because it provides useful 
information that must be provided to update a target directory hierarchy to match a source 
hierarchy. The "Common subdirectories" messages are written by System V and 4.3 BSD when 
the -r option is specified. They are allowed here but are not required because they are reporting 
on something that is the same, not reporting a difference, and are not needed to update a target 
hierarchy. 

The -c option, which writes output in a format using lines of context, has been included. The 
format is useful for a variety of reasons, among them being much improved readability and the 
ability to understand difference changes when the target file has line numbers that differ from 
another similar, but slightly different, copy. The patch utility is most valuable when working 
with difference listings using the context format. The BSD version of -c takes an optional 
argument specifying the amount of context. Rather than overloading -c and breaking the Utility 
Syntax Guidelines for diff, the standard developers decided to add a separate option for 
specifying a context diff with a specified amount of context (-C). Also, the format for context 
diffs was extended slightly in 4.3 BSD to allow multiple changes that are within context lines 
from each other to be merged together. The output format contains an additional four asterisks 
after the range of affected lines in the first file name. This was to provide a flag for old programs 
(like old versions of patch) that only understand the old context format. The version of context 
described here does not require that multiple changes within context lines be merged, but it does 
not prohibit it either. The extension is upward-compatible, so any vendors that wish to retain the 
old version of diff can do so by adding the extra four asterisks (that is, utilities that currently use 
diff and understand the new merged format will also understand the old unmerged format, but 
not vice versa). 

The substitute command was added as an additional format for the -e option. This was added to 
provide implementations a way to fix the classic "dot alone on a line" bug present in many 
versions of diff. Since many implementations have fixed this bug, the standard developers 
decided not to standardize broken behavior, but rather to provide the necessary tool for fixing 
the bug. One way to fix this bug is to output two periods whenever a lone period is needed, then 
terminate the append command with a period, and then use the substitute command to convert 
the two periods into one period. 

The BSD-derived -r option was added to provide a mechanism for using diff to compare two file 
system trees. This behavior is useful, is standard practice on all BSD-derived systems, and is not 
easily reproducible with the find utility. 

The requirement that diff not compare files in some circumstances, even though they have the 
same name, is based on the actual output of historical implementations. The message specified 
here is already in use when a directory is being compared to a non-directory. It is extended here 
to preclude the problems arising from running into FIFOs and other files that would cause diff to 
hang waiting for input with no indication to the user that diff was hung. In most common usage, 
diff -r should indicate differences in the file hierarchies, not the difference of contents of devices 
pointed to by the hierarchies. 

Many early implementations of diff require seekable files. Since the System Interfaces volume of 
IEEE Std. 1003.1-200x supports named pipes, the standard developers decided that such a 
restriction was unreasonable. Note also that the allowed file name - almost always refers to a 
pipe. 


Commands and Utilities, Issue 6 


357 



diff 


Utilities 


13529 No directory search order is specified for diff. The historical ordering is, in fact, not optimal, in 

13530 that it prints out all of the differences at the current level, including the statements about all 

13531 common subdirectories before recursing into those subdirectories. 

13532 The message: 

13533 "diff %s %s %s\n", <diff_options>, <filenamel>, <filename2> 

13534 does not vary by locale because it is the representation of a command, not an English sentence. 

13535 FUTURE DIRECTIONS 

13536 None. I 

13537 SEE ALSO 

13538 cmp, comm, ed 

13539 CHANGE HISTORY 

13540 First released in Issue 2. 

13541 Issue 4 

13542 Aligned with the ISO/IEC 9945-2:1993 standard. 

13543 Issue 5 

13544 FUTURE DIRECTIONS section added. 

13545 Issue 6 

13546 The following new requirements on POSIX implementations derive from alignment with the 

13547 Single UNIX Specification: 

13548 • The -f option is added. 

13549 The output format for -c or -C format is changed to align with changes to the IEEE P1003.2b I 

13550 draft standard resulting from PASC Interpretation 1003.2-92 #71. I 

13551 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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13552 NAME 

13553 dirname — return the directory portion of path name 

13554 SYNOPSIS 

13555 dirname string 


13556 DESCRIPTION 

13557 The string operand shall be treated as a path name, as defined in the System Interface Definitions I 

13558 volume of IEEE Std. 1003.1-200x, Section 3.272, Path Name. The string string shall be converted I 

13559 to the name of the directory containing the file name corresponding to the last path name 

13560 component in string, performing actions equivalent to the following steps in order: 


13561 

13562 

13563 


1. If string is //, skip steps 2 to 5. 

2. If string consists entirely of slash characters, string shall be set to a single slash character. In 
this case, skip steps 3 to 8. 


13564 

13565 

13566 


3. If there are any trailing slash characters in string , they shall be removed. 

4. If there are no slash characters remaining in string, string shall be set to a single period 
character. In this case, skip steps 5 to 8. 


13567 

13568 

13569 


5. If there are any trailing non-slash characters in string, they shall be removed. 

6. If the remaining string is //, it is implementation-dependent whether steps 7 and 8 are 
skipped or processed. 


13570 7. If there are any trailing slash characters in string, they shall be removed. 

13571 8. If the remaining string is empty, string shall be set to a single slash character. 


13572 The resulting string shall be written to standard output. 


13573 OPTIONS 

13574 None. 


13575 OPERANDS 

13576 The following operand shall be supported: 

13577 string A string. 

13578 STDIN 

13579 Not used. 


13580 INPUT FILES 

13581 None. 


13582 ENVIRONMENT VARIABLES 


13583 

The following environment variables shall affect the execution of dirname: 

13584 

13585 

13586 

13587 

13588 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale will be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

13589 

13590 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

13591 

13592 

13593 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 
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13594 LC_MESSAGES 

13595 Determine the locale that should be used to affect the format and contents of 

13596 diagnostic messages written to standard error. 

13597 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

13598 ASYNCHRONOUS EVENTS 

13599 Default. 

13600 STDOUT 

13601 The dirname utility shall write a line to the standard output in the following format: 

13602 "%s\n", <resulting string> 

13603 STDERR 

13604 Used only for diagnostic messages. 

13605 OUTPUT FILES 

13606 None. 

13607 EXTENDED DESCRIPTION 

13608 None. 

13609 EXIT STATUS 

13610 The following exit values shall be returned: 

13611 0 Successful completion. 

13612 >0 An error occurred. 

13613 CONSEQUENCES OF ERRORS 

13614 Default. 

13615 APPLICATION USAGE 

13616 The definition of pathname specifies implementation-dependent behavior for path names starting 

13617 with two slash characters. Therefore, applications shall not arbitrarily add slashes to the I 

13618 beginning of a path name unless they can ensure that there are more or less than two or are 

13619 prepared to deal with the implementation-dependent consequences. 

13620 EXAMPLES 


13621 

Command 

Results 

13622 

dirname / 

/ 

13623 

dirname // 

/ or // 

13624 

dirname / a/b / 

/a 

13625 

dirname / /a//b // 

lla 

13626 

dirname 

Unspecified 

13627 

dirname a 

• ($? = 0) 

13628 

dirname "" 

• ($? - 0) 

13629 

dirname / a 

/ 

13630 

dirname / a/b 

/a 

13631 

dirname a/b 

a 


13632 RATIONALE 

13633 The dirname utility originated in System III. It has evolved through the System V releases to a 

13634 version that matches the requirements specified in this description in System V Release 3. 4.3 

13635 BSD and earlier versions did not include dirname. 

13636 The behaviors of basename and dirname in this volume of IEEE Std. 1003.1-200x have been 

13637 coordinated so that when string is a valid path name: 
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13638 $ (basename "string") 

13639 would be a valid file name for the file in the directory: 

13640 $ (dirname "string") 

13641 This would not work for the versions of these utilities in early proposals due to the way 

13642 processing of trailing slashes was specified. Consideration was given to leaving processing 

13643 unspecified if there were trailing slashes, but this cannot be done; the System Interface I 

13644 Definitions volume of IEEE Std. 1003.1-200x, Section 3.272, Path Name allows trailing slashes. I 

13645 The basename and dirname utilities have to specify consistent handling for all valid path names. 

13646 FUTURE DIRECTIONS 

13647 None. 

13648 SEE ALSO 

13649 basename, Section 2.5 on page 43 

13650 CHANGE HISTORY 

13651 First released in Issue 2. 

13652 Issue 4 

13653 Aligned with the ISO/IEC 9945-2:1993 standard. 
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13654 

13655 

13656 

13657 

13658 

13659 

13660 

13661 

13662 

13663 

13664 

13665 

13666 

13667 

13668 

13669 

13670 

13671 

13672 

13673 

13674 

13675 

13676 

13677 

13678 

13679 

13680 

13681 

13682 

13683 

13684 

13685 

13686 

13687 

13688 

13689 

13690 

13691 

13692 

13693 

13694 

13695 


NAME 

du — estimate file space usage 

SYNOPSIS 

UP du [—a | —s][—kx][-H | -L][ file ... ] I 

I 

DESCRIPTION 

By default, the du utility shall write to standard output the size of the file space allocated to, and 
the size of the file space allocated to each subdirectory of, the file hierarchy rooted in each of the 
specified files. By default, when a symbolic link is encountered on the command line or in the I 
file hierarchy, du shall count the size of the symbolic link (rather than the file referenced by the I 
link), and shall not follow the link to another portion of the file hierarchy. The size of the file I 
space allocated to a file of type directory shall be defined as the sum total of space allocated to I 
all files in the file hierarchy rooted in the directory plus the space allocated to the directory itself. I 

When du cannot shit {) files or stat {) or read directories, it shall report an error condition and the 
final exit status is affected. Files with multiple links shall be counted and written for only one 
entry. The directory entry that is selected in the report is unspecified. By default, file sizes shall 
be written in 512-byte units, rounded up to the next 512-byte unit. 

OPTIONS 

The du utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-a In addition to the default output, report the size of each file not of type directory in 

the file hierarchy rooted in the specified file. Regardless of the presence of the -a 
option, non-directories given as file operands shall always be listed. I 

-H If a symbolic link is specified on the command line, du shall count the size of the I 

file or file hierarchy referenced by the link. I 

-k Write the files sizes in units of 1024 bytes, rather than the default 512-byte units. I 

-L If a symbolic link is specified on the command line or encountered during the I 

traversal of a file hierarchy, du shall count the size of the file or file hierarchy I 
referenced by the link. I 

-s Instead of the default output, report only the total sum for each of the specified 

files. 

-x When evaluating file sizes, evaluate only those files that have the same device as 

the file specified by the file operand. 

Specifying more than one of the mutually-exclusive options -H and -L shall not be considered I 
an error. The last option specified shall determine the behavior of the utility. I 

OPERANDS 

The following operand shall be supported: 

file The path name of a file whose size is to be written. If no file is specified, the current 

directory shall be used. 

STDIN 

Not used. 
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13696 INPUT FILES 

13697 None. 


13698 ENVIRONMENT VARIABLES 

13699 The following environment variables shall affect the execution of du: 


13700 

13701 

13702 

13703 

13704 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


13705 LC_ALL If set to a non-empty string value, override the values of all the other 

13706 internationalization variables. 


13707 

13708 

13709 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


13710 LC_MESSAGES 

13711 Determine the locale that should be used to affect the format and contents of 

13712 diagnostic messages written to standard error. 

13713 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


13714 ASYNCHRONOUS EVENTS 

13715 Default. 


13716 STDOUT 

13717 The output from du shall consist of the amount of the space allocated to a file and the name of 

13718 the file, in the following format: 

13719 "%d %s\n", <size>, <pathname> 

13720 STDERR 

13721 Used only for diagnostic messages. 

13722 OUTPUT FILES 

13723 None. 


13724 EXTENDED DESCRIPTION 

13725 None. 


13726 EXIT STATUS 

13727 The following exit values shall be returned: 

13728 0 Successful completion. 

13729 >0 An error occurred. 


13730 CONSEQUENCES OF ERRORS 

13731 Default. 
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13732 APPLICATION USAGE 

13733 Application writers should note that this utility need not be provided on systems that do not 

13734 support the User Portability Utilities option. 

13735 EXAMPLES 

13736 None. 

13737 RATIONALE 

13738 The use of 512-byte units is historical practice and maintains compatibility with Is and other 

13739 utilities in this volume of IEEE Std. 1003.1-200x. This does not mandate that the file system itself 

13740 be based on 512-byte blocks. The -k option was added as a compromise measure. It was agreed 

13741 by the standard developers that 512 bytes was the best default unit because of its complete 

13742 historical consistency on System V ( versus the mixed 512/1024-byte usage on BSD systems), and 

13743 that a -k option to switch to 1024-byte units was a good compromise. Users who prefer the 

13744 1024-byte quantity can easily alias du to du -k without breaking the many historical scripts 

13745 relying on the 512-byte units. 

13746 The -b option was added to an early proposal to provide a resolution to the situation where 

13747 System V and BSD systems give figures for file sizes in blocks, which is an implementation- 

13748 dependent concept. (In common usage, the block size is 512 bytes for System V and 1024 bytes 

13749 for BSD systems.) However, -b was later deleted, since the default was eventually decided as 

13750 512-byte units. 

13751 Historical file systems provided no way to obtain exact figures for the space allocation given to 

13752 files. There are two known areas of inaccuracies in historical file systems: cases of indirect blocks 

13753 being used by the file system or sparse files yielding incorrectly high values. An indirect block is 

13754 space used by the file system in the storage of the file, but that need not be counted in the space 

13755 allocated to the file. A sparse file is one in which an lseek( ) call has been made to a position 

13756 beyond the end of the file and data has subsequently been written at that point. A file system 

13757 need not allocate all the intervening zero-filled blocks to such a file. It is up to the 

13758 implementation to define exactly how accurate its methods are. 

13759 The -a and -s options were mutually-exclusive in the original version of du. The POSIX Shell 

13760 and Utilities description is implied by the language in the SVID where -s is described as causing 

13761 "only the grand total" to be reported. Some systems may produce output for -sa, but a Strictly 

13762 Conforming POSIX Shell and Utilities Application cannot use that combination. 

13763 The -a and -s options were adopted from the SVID except that the System V behavior of not 

13764 listing non-directories explicitly given as operands, unless the -a option is specified, was 

13765 considered a bug; the BSD-based behavior (report for all operands) is mandated. The default 

13766 behavior of du in the SVID with regard to reporting the failure to read files (it produces no 

13767 messages) was considered counter-intuitive, and thus it was specified that the POSIX Shell and 

13768 Utilities default behavior shall be to produce such messages. These messages can be turned off 

13769 with shell redirection to achieve the System V behavior. 

13770 The -x option is historical practice on recent BSD systems. It has been adopted by this volume of 

13771 IEEE Std. 1003.1-200x because there was no other historical method of limiting the du search to a 

13772 single file hierarchy. This limitation of the search is necessary to make it possible to obtain file 

13773 space usage information about a file system on which other file systems are mounted, without 

13774 having to resort to a lengthy find and azvk script. 

13775 FUTURE DIRECTIONS 

13776 None. 
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13777 SEE ALSO 

13778 Is 

13779 CHANGE HISTORY 

13780 First released in Issue 2. 

13781 Issue 4 

13782 Aligned with the ISO/IEC 9945-2:1993 standard. 

13783 Issue 6 

13784 This utility is now marked as part of the User Portability Utilities option. 

13785 The APPLICATION USAGE section is added. 

13786 This utility is reinstated, as the LEGACY marking was incorrect in Issue 5. 

13787 The obsolescent -r option has been removed. 

13788 The Open Group corrigenda item U025/3 has been applied. The du utility had incorrectly been 

13789 marked LEGACY. I 

13790 The -H and -L options for symbolic links are added as described in the IEEE P1003.2b draft I 

13791 standard. I 
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NAME 

echo — write arguments to standard output 

SYNOPSIS 

echo [string . . . ] 

DESCRIPTION 

The echo utility writes its arguments to standard output, followed by a <newline> character. If 
there are no arguments, only the <newline> character is written. 

OPTIONS 

The echo utility shall not recognize the "—" argument in the manner specified by Guideline 10 I 
of the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax I 
Guidelines; "—" shall be recognized as a string operand. I 

man Implementations shall not support any options. 

OPERANDS 

The following operands shall be supported: 

man string A string to be written to standard output. If any operand is -n, it shall be treated 

as a string, not an option. The following character sequences shall be recognized 
within any of the arguments: 

\a Write an <alert> character. 

\b Write a <backspace> character. 

\c Suppress the <newline> character that otherwise follows the final 
argument in the output. All characters following the ' \ c' in the 
arguments shall be ignored. 

\ f Write a <form-feed> character. 

\n Write a <newline> character. 

\r Write a <carriage-return> character. 

\t Write a <tab> character. 

\v Write a <vertical-tab> character. 

\ \ Write a backslash character. 

\0 num Write an 8-bit value that is the zero, one, two, or three-digit octal number 
niim. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of echo : 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 
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13833 

LC_ALL 

If set to a non-empty string value, override the values of all the other 

13834 


internationalization variables. 

13835 MAN 

13836 

13837 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

13838 

LC_MESSAGES 

13839 


Determine the locale that should be used to affect the format and contents of 

13840 


diagnostic messages written to standard error. 

13841 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


13842 ASYNCHRONOUS EVENTS 

13843 Default. 

13844 STDOUT 

13845 The echo utility arguments shall be separated by single <space> characters and a <newline> 

13846 man character follows the last argument. Output transformations shall occur based on the escape 

13847 sequences in the input. See the OPERANDS section. 

13848 STDERR 

13849 Used only for diagnostic messages. 

13850 OUTPUT FILES 

13851 None. 

13852 EXTENDED DESCRIPTION 

13853 None. 

13854 EXIT STATUS 

13855 The following exit values shall be returned: 

13856 0 Successful completion. 

13857 >0 An error occurred. 

13858 CONSEQUENCES OF ERRORS 

13859 Default. 

13860 APPLICATION USAGE 

13861 In the ISO/IEC 9945-2:1993 standard, it was not possible to use echo portably across all systems 

13862 that were not XSI-conformant unless both -n (as the first argument) and escape sequences were 

13863 omitted. 

13864 The printf utility can be used portably to emulate any of the traditional behaviors of the echo 

13865 utility as follows: 

13866 • The historic System V echo and the current requirements in this volume of 

13867 IEEE Std. 1003.1-200x are equivalent to: 

13868 print f "%b\n" "$*" 

13869 • The BSD echo is equivalent to: 


13870 

if [ "X$l" 

= "X- 

13871 

then 


13872 

shift 


13873 

printf 

" % s " 

13874 

else 


13875 

printf 

" % s \ n 
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13876 fi 

13877 New applications are encouraged to use print/ instead of echo. 

13878 EXAMPLES 

13879 None. 

13880 RATIONALE 

13881 The echo utility has not been made obsolescent because of its extremely widespread use in 

13882 historical applications. Portable applications that wish to do prompting without <newline>s or 

13883 that could possibly be expecting to echo a -n, should use the new print/ utility derived from the 

13884 Ninth Edition system. 

13885 As specified, echo writes its arguments in the simplest of ways. The two different historical 

13886 versions of echo vary in fatally incompatible ways. 

13887 The BSD echo checks the first argument for the string -n which causes it to suppress the 

13888 <newline> character that would otherwise follow the final argument in the output. 

13889 The System V echo does not support any options, but allows escape sequences within its 

13890 operands, as described in the OPERANDS section. 

13891 The echo utility does not support Utility Syntax Guideline 10 because historical applications 

13892 depend on echo to echo all of its arguments, except for the -n option in the BSD version. 

13893 FUTURE DIRECTIONS 

13894 None. 

13895 SEE ALSO 

13896 print/ 

13897 CHANGE HISTORY 

13898 First released in Issue 2. 


13899 Issue 4 

13900 

13901 Issue 5 

13902 

13903 

13904 Issue 6 

13905 

13906 

13907 

13908 

13909 


Aligned with the ISO/IEC 9945-2:1993 standard. 

In the OPTIONS section, the last sentence is changed to indicate that implementations "do not" 
support any options; in the previous issue this said "need not". 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• A set of character sequences is defined as string operands. 

• LC_CTYPE is added to the list of environment variables affecting echo. 

• In the OPTIONS section, implementations shall not support any options. 
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NAME 

ed — edit text 

SYNOPSIS 

ed [—p string ][—s] [file] 

DESCRIPTION 

The ed utility is a line-oriented text editor that uses two modes: command mode and input mode. 

In command mode the input characters shall be interpreted as commands, and in input mode 

they shall be interpreted as text. See the EXTENDED DESCRIPTION section. 

OPTIONS 

The ed utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-B string Use string as the prompt string when in command mode. By default, there shall be 
no prompt string. 

-s Suppress the writing of byte counts by e, E, r, and w commands and of the ' !' 

prompt after a ! command. 

OPERANDS 

The following operand shall be supported: 

file If the file argument is given, ed shall simulate an e command on the file named by 

the path name, file, before accepting commands from the standard input. If the file 
operand is ' - ', the results are unspecified. 

STDIN 

The standard input shall be a text file consisting of commands, as described in the EXTENDED I 

DESCRIPTION section. 

INPUT FILES 

The input files shall be text files. I 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of ed: 

HOME Determine the path name of the user 7 s home directory. 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements within regular expressions. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes within regular 
expressions. 
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13953 LC_MESSAGES 

13954 Determine the locale that should be used to affect the format and contents of 

13955 diagnostic messages written to standard error and informative messages written to 

13956 standard output. 

13957 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

13958 ASYNCHRONOUS EVENTS 

13959 The ed utility shall take the standard action for all signals (see the ASYNCHRONOUS EVENTS 

13960 section in Section 1.11 on page 25) with the following exceptions: 

13961 SIGINT The ed utility shall interrupt its current activity, write the string " ? \ n " to standard 

13962 output, and return to command mode (see the EXTENDED DESCRIPTION 

13963 section). 

13964 SIGHUP If the buffer is not empty and has changed since the last write, the ed utility shall 

13965 attempt to write a copy of the buffer in a file. First, the file named ed.hup in the 

13966 current directory shall be used; if that fails, the file named ed.hup in the directory 

13967 named by the HOME environment variable shall be used. In any case, the ed utility 

13968 shall exit without returning to command mode. I 

13969 SIGQUIT The ed utility shall ignore this event. I 

13970 STDOUT 

13971 Various editing commands and the prompting feature (see -p) write to standard output, as 

13972 described in the EXTENDED DESCRIPTION section. 

13973 STDERR 

13974 Used only for diagnostic messages. 

13975 OUTPUT FILES 

13976 The output files shall be text files whose formats are dependent on the editing commands given. 

13977 EXTENDED DESCRIPTION 

13978 The ed utility shall operate on a copy of the file it is editing; changes made to the copy shall have 

13979 no effect on the file until a w (write) command is given. The copy of the text is called the buffer. 

13980 Commands to ed have a simple and regular structure: zero, one, or two addresses followed by a 

13981 single-character command, possibly followed by parameters to that command. These addresses 

13982 specify one or more lines in the buffer. Every command that requires addresses has default 

13983 addresses, so that the addresses very often can be omitted. If the -p option is specified, the 

13984 prompt string shall be written to standard output before each command is read. 

13985 In general, only one command can appear on a line. Certain commands allow text to be input. 

13986 This text is placed in the appropriate place in the buffer. While ed is accepting text, it is said to be 

13987 in input mode. In this mode, no commands shall be recognized; all input is merely collected. 

13988 Input mode is terminated by entering a line consisting of two characters: a period (' .') 

13989 followed by a <newline> character. This line is not considered part of the input text. 

13990 Regular Expressions in ed 

13991 The ed utility shall support basic regular expressions, as described in the System Interface I 

13992 Definitions volume of IEEE Std. 1003.1-200x, Section 9.3, Basic Regular Expressions. Since I 

13993 regular expressions in ed are always matched against single lines, never against any larger I 

13994 section of text, there is no way for a regular expression to match a <newline> character. A null 

13995 RE shall be equivalent to the last RE encountered. 

13996 Regular expressions are used in addresses to specify lines, and in some commands (for example, 

13997 the s substitute command) to specify portions of a line to be substituted. 
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Addresses in ed 

Addressing in ed relates to the current line. Generally, the current line is the last line affected by a 
command. The current line number is the address of the current line. If the edit buffer is not 
empty, the initial value for the current line shall be the last line in the edit buffer; otherwise, zero. 

Addresses shall be constructed as follows: 

1. The period character (' .') shall address the current line. 

2. The dollar sign character (' $') shall address the last line of the edit buffer. 

3. The positive decimal number n shall address the nth line of the edit buffer. 

4. The apostrophe-x character pair ("' x") shall address the line marked with the mark name 
character x, which shall be a lowercase letter from the portable character set. It shall be an 
error if the character has not been set to mark a line or if the line that was marked is not 
currently present in the edit buffer. 

5. A BRE enclosed by slash characters (' /') shall address the first line found by searching 
forwards from the line following the current line toward the end of the edit buffer and 
stopping at the first line containing a string matching the BRE. The BRE consisting of a null 
BRE delimited by a pair of slash characters shall address the next line containing the last 
BRE encountered. In addition, the second slash can be omitted at the end of a command 
line. Within the BRE, a backslash-slash pair (" \ /") shall represent a literal slash instead of 
the BRE delimiter. If necessary, the search shall wrap around to the beginning of the buffer 
and continue up to and including the current line, so that the entire buffer is searched. 

6. A BRE enclosed by question-mark characters (' ?') shall address the first line found by 
searching backwards from the line preceding the current line toward the beginning of the 
edit buffer and stopping at the first line containing a string matching the BRE. The BRE 
consisting of a null BRE delimited by a pair of question-mark characters ("??") shall 
address the previous line containing the last BRE encountered. In addition, the second 
question-mark can be omitted at the end of a command line. Within the BRE, a backslash- 
question-mark pair ("\?") shall represent a literal question mark instead of the BRE 
delimiter. If necessary, the search shall wrap around to the end of the buffer and continue 
up to and including the current line, so that the entire buffer is searched. 

7. A plus-sign (' + ') or hyphen character ) followed by a decimal number shall address 
the current line plus or minus the number. A plus-sign or hyphen character not followed 
by a decimal number shall address the current line plus or minus 1. 

Addresses can be followed by zero or more address offsets, optionally <blank>-separated. 
Address offsets are constructed as follows: 

• A plus-sign or hyphen character followed by a decimal number shall add or subtract, 
respectively, the indicated number of lines to or from the address. A plus-sign or hyphen 
character not followed by a decimal number shall add or subtract 1 to or from the address. 

• A decimal number shall add the indicated number of lines to the address. 

It shall not be an error for an intermediate address value to be less than zero or greater than the 
last line in the edit buffer. It shall be an error for the final address value to be less than zero or 
greater than the last line in the edit buffer. It shall be an error if a search for a BRE fails to find a 
matching line. 

Commands accept zero, one, or two addresses. If more than the required number of addresses 
are provided to a command that requires zero addresses, it shall be an error. Otherwise, if more 
than the required number of addresses are provided to a command, the addresses specified first 
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shall be evaluated and then discarded until the maximum number of valid addresses remain, for 
the specified command. 

Addresses shall be separated from each other by a comma (' , ') or semicolon character (' ;'). 
In the case of a semicolon separator, the current line (' .') shall be set to the first address, and 
only then will the second address be calculated. This feature can be used to determine the 
starting line for forwards and backwards searches; see rules 5. and 6. 

Addresses can be omitted on either side of the comma or semicolon separator, in which case the 
resulting address pairs shall be as follows: 


Specified 

Resulting 

r 

1 , $ 

, addr 

1 ,a ddr 

addr , 

addr , addr 

r 

• ; $ 

; addr 

. ; addr 

addr ; 

addr ; addr 


Any <blank> characters included between addresses, address separators, or address offsets shall I 
be ignored. I 

Commands in ed 

In the following list of ed commands, the default addresses are shown in parentheses. The 
number of addresses shown in the default shall be the number expected by the command. The 
parentheses are not part of the address; they show that the given addresses are the default. 

It is generally invalid for more than one command to appear on a line. However, any command 
(except e, E, f, q, Q, r, w, and !) can be suffixed by the letter 1, n, or p; in which case, except for 
the 1 , n, and p commands, the command shall be executed and then the new current line shall be 
written as described below under the 1, n, and p commands. When an 1, n, or p suffix is used 
with an 1 , n, or p command, the command shall write to standard output as described below, but 
it is unspecified whether the suffix writes the current line again in the requested format or 
whether the suffix has no effect. For example, the pi command (base p command with an 1 
suffix) shall either write just the current line or write it twice—once as specified for p and once 
as specified for 1. Also, the g, G, v, and V commands shall take a command as a parameter. 

Each address component can be preceded by zero or more <blank> characters. The command 
letter can be preceded by zero or more <blank> characters. If a suffix letter (1, n, or p) is given, I 
the application shall ensure that it immediately follows the command. I 

The e, E, f, r, and w commands shall take an optional file parameter, separated from the 
command letter by one or more <blank> characters. 

If changes have been made in the buffer since the last w command that wrote the entire buffer, 
ed shall warn the user if an attempt is made to destroy the editor buffer via the e or q commands. 
The ed utility shall write the string: 

"?\n" 

(followed by an explanatory message if help mode has been enabled via the H command) to 
standard output and shall continue in command mode with the current line number unchanged. 

If the e or q command is repeated with no intervening command, it shall take effect. 

If a terminal disconnect is detected: I 
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• If the buffer is not empty and has changed since the last write, the ed utility shall attempt to 
write a copy of the buffer to a file named ed.hup in the current directory. If this write fails, ed 
shall attempt to write a copy of the buffer to a file name ed.hup in the directory named by the 
HOME environment variable. If both these attempts fail, ed shall exit without saving the 
buffer. 

• The ed utility shall not write the file to the currently remembered path name or return to 
command mode, and shall terminate with a non-zero exit status. 

If an end-of-file is detected on standard input: 

• If the ed utility is in input mode, ed shall terminate input mode and return to command mode. 
It is unspecified if any partially entered lines (that is, input text without a terminating 
<newline> character) are discarded from the input text. 

• If the ed utility is in command mode, it shall act as if a q command had been entered. 

If the closing delimiter of an RE or of a replacement string (for example, ' /') in a g, G, s, v, or V 
command would be the last character before a <newline> character, that delimiter can be 
omitted, in which case the addressed line shall be written. For example, the following pairs of 
commands are equivalent: 

s/sl/s2 s/sl/s2/p 

g/sl g/sl/p 

?sl ?sl? 

If an invalid command is entered, ed shall write the string: 

"?\n" 

(followed by an explanatory message if help mode has been enabled via the H command) to 
standard output and shall continue in command mode with the current line number unchanged. 

Append Command 

Synopsis: (.) a 

<text> 


The a command shall read the given text and append it after the addressed line; the current line 
number shall become the address of the last inserted line or, if there were none, the addressed 
line. Address 0 shall be valid for this command; it shall cause the appended text to be placed at 
the beginning of the buffer. 

Change Command 

Synopsis: (., .) c 

<text> 


The c command shall delete the addressed lines, then accept input text that replaces these lines; 
the current line shall be set to the address of the last line input; or, if there were none, at the line 
after the last line deleted; if the lines deleted were originally at the end of the buffer, the current 
line number shall be set to the address of the new last line; if no lines remain in the buffer, the 
current line number shall be set to zero. Address 0 shall be valid for this command; it shall be I 
interpreted as if address 1 were specified. I 
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Delete Command 

Synopsis: (., .) d 

The d command shall delete the addressed lines from the buffer. The address of the line after the 
last line deleted shall become the current line number; if the lines deleted were originally at the 
end of the buffer, the current line number shall be set to the address of the new last line; if no 
lines remain in the buffer, the current line number shall be set to zero. 

Edit Command 

Synopsis: e [file] 

The e command shall delete the entire contents of the buffer and then read in the file named by 
the path name file. The current line number shall be set to the address of the last line of the 
buffer. If no path name is given, the currently remembered path name, if any, shall be used (see 
the f command). The number of bytes read shall be written to standard output, unless the -s 
option was specified, in the following format: 

"%d\n", <number of bytes read> 

The name file shall be remembered for possible use as a default path name in subsequent e, E, r, 
and w commands. If file is replaced by ' !', the rest of the line shall be taken to be a shell 
command line whose output is to be read. Such a shell command line shall not be remembered 
as the current file. All marks shall be discarded upon the completion of a successful e command. 
If the buffer has changed since the last time the entire buffer was written, the user shall be 
warned, as described previously. 

Edit Without Checking Command 

Synopsis: E [file] 

The E command shall possess all properties and restrictions of the e command except that the 
editor shall not check to see whether any changes have been made to the buffer since the last w 
command. 

File Name Command 

Synopsis: f [file] 

lifile is given, the f command shall change the currently remembered path name to file; whether 
the name is changed or not, it shall then write the (possibly new) currently remembered path 
name to the standard output in the following format: 

"%s\n", <pathname> 

The current line number shall be unchanged. 

Global Command 

Synopsis: (l,$)g /RE/command list 

In the g command, the first step shall be to mark every line that matches the given RE. Then, 
going sequentially from the beginning of the file to the end of the file, the given command list 
shall be executed for each marked line, with the current line number set to the address of that 
line. Any line modified by the command list shall be unmarked. When the g command completes, 
the current line number shall have the value assigned by the last command in the command list. 
If there were no matching lines, the current line number shall not be changed. A single command 
or the first of a list of commands shall appear on the same line as the global command. All lines 
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of a multi-line list except the last line shall be ended with a backslash; the a, i, and c commands I 
and associated input are permitted. The ' .' terminating input mode can be omitted if it would 
be the last line of the command list. An empty command list shall be equivalent to the p command. 
The use of the g, G, v, V, and ! commands in the command list produces undefined results. Any 
character other than <space> or <newline> can be used instead of a slash to delimit the RE. 
Within the RE, the RE delimiter itself can be used as a literal character if it is preceded by a 
backslash. 

Interactive Global Command 

Synopsis: (1, $) G/ RE/ 

In the G command, the first step shall be to mark every line that matches the given RE. Then, 
for every such line, that line shall be written, the current line number shall be set to the address 
of that line, and any one command (other than one of the a, c, i, g, G, v, and V commands) shall 
be read and executed. A <newline> character shall act as a null command (causing no action to 
be taken on the current line); an ' & ' shall cause the re-execution of the most recent non-null 
command executed within the current invocation of G. Note that the commands input as part 
of the execution of the G command can address and affect any lines in the buffer. The final value 
of the current line number shall be the value set by the last command successfully executed. 
(Note that the last command successfully executed shall be the G command itself if a command 
fails or the null command is specified.) If there were no matching lines, the current line number 
shall not be changed. The G command can be terminated by a SIGINT signal. Any character 
other than <space> or <newline> can be used instead of a slash to delimit the RE and the 
replacement. Within the RE, the RE delimiter itself can be used as a literal character if it is 
preceded by a backslash. 

Help Command 

Synopsis: h 

The h command shall write a short message to standard output that explains the reason for the 
most recent ' ?' notification. The current line number shall be unchanged. 

Help-Mode Command 

Synopsis: H 

The H command shall cause ed to enter a mode in which help messages (see the h command) 

shall be written to standard output for all subsequent ' ?' notifications. The H command 

alternatively shall turn this mode on and off; it is initially off. If the help-mode is being turned 
on, the H command also explains the previous ' ?' notification, if there was one. The current 
line number shall be unchanged. 

Insert Command 

Synopsis: (.) i 

<text> 


The i command shall insert the given text before the addressed line; the current line is set to the 
last inserted line or, if there was none, to the addressed line. This command differs from the a 
command only in the placement of the input text. Address 0 shall be valid for this command; it I 
shall be interpreted as if address 1 were specified. I 
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14210 Join Command 

14211 Synopsis: (., . +1) j 

14212 The j command shall join contiguous lines by removing the appropriate <newline> characters. If 

14213 exactly one address is given, this command shall do nothing. If lines are joined, the current line 

14214 number shall be set to the address of the joined line; otherwise, the current line number shall be 

14215 unchanged. 

14216 Mark Command 

14217 Synopsis: (.) kx 

14218 The k command shall mark the addressed line with name x, which the application shall ensure is I 

14219 a lowercase letter from the portable character set. The address "' x" shall then refer to this line; I 

14220 the current line number shall be unchanged. 

14221 List Command 

14222 Synopsis: ( ., .) 1 

14223 The 1 command shall write to standard output the addressed lines in a visually unambiguous I 

14224 form. The characters listed in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

14225 Table 5-1, Escape Sequences and Associated Actions {'W, ' \a', '\b', ' \f', ' \r', '\t', I 

14226 ' \v') shall be written as the corresponding escape sequence; the ' \n' in that table is not 

14227 applicable. Non-printable characters not in the table shall be written as one three-digit octal 

14228 number (with a preceding backslash character) for each byte in the character (most significant 

14229 byte first). If the size of a byte on the system is greater than nine bits, the format used for non- 

14230 printable characters is implementation-dependent. 

14231 Long lines shall be folded, with the point of folding indicated by writing backslash/<newline> 

14232 character; the length at which folding occurs is unspecified, but should be appropriate for the 

14233 output device. The end of each line shall be marked with a ' $', and ' $' characters within the I 

14234 text shall be written with a preceding backslash. An 1 command can be appended to any other I 

14235 command other than e, E, f, q, Q, r, w, or !. The current line number shall be set to the address of 

14236 the last line written. 

14237 Move Command 

14238 Synopsis: (.,.)m address 

14239 The m command shall reposition the addressed lines after the line addressed by address. 

14240 Address 0 shall be valid for address and cause the addressed lines to be moved to the beginning 

14241 of the buffer. It shall be an error if address address falls within the range of moved lines. The 

14242 current line number shall be set to the address of the last line moved. 

14243 Number Command 

14244 Synopsis: (., .) n 

14245 The n command shall write to standard output the addressed lines, preceding each line by its 

14246 line number and a <tab> character; the current line number shall be set to the address of the last 

14247 line written. The n command can be appended to any command other than e, E, f, q, Q, r, w, or !. 
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Print Command 

Synopsis: (., .) p 

The p command shall write to standard output the addressed lines; the current line number shall 
be set to the address of the last line written. The p command can be appended to any command 
other than e, E, f, q, Q, r, w, or !. 

Prompt Command 

Synopsis: P 

The P command shall cause ed to prompt with an asterisk (' *') (or string, if -p is specified) for 
all subsequent commands. The P command alternatively shall turn this mode on and off; it shall 
be initially on if the -p option is specified; otherwise, off. The current line number shall be 
unchanged. 

Quit Command 

Synopsis: q 

The q command shall cause ed to exit. If the buffer has changed since the last time the entire 
buffer was written, the user shall be warned, as described previously. 

Quit Without Checking Command 

Synopsis: Q 

The Q command shall cause ed to exit without checking whether changes have been made in the 
buffer since the last w command. 

Read Command 

Synopsis: ($) r [file] 

The r command shall read in the file named by the path name file and append it after the 
addressed line. If no file argument is given, the currently remembered path name, if any, shall be 
used (see the e and f commands). The currently remembered path name shall not be changed 
unless there is no remembered path name. Address 0 shall be valid for r and shall cause the file 
to be read at the beginning of the buffer. If the read is successful, and -s was not specified, the 
number of bytes read shall be written to standard output in the following format: 

"%d\n", <number of bytes read> 

The current line number shall be set to the address of the last line read in. If file is replaced by 
' !', the rest of the line shall be taken to be a shell command line whose output is to be read. 
Such a shell command line shall not be remembered as the current path name. 

Substitute Command 

Synopsis: (., . ) s/ RE/replacement/flags 

The s command shall search each addressed line for an occurrence of the specified RE and 
replace either the first or all (non-overlapped) matched strings with the replacement; see the 
following description of the g suffix. It is an error if the substitution fails on every addressed 
line. Any character other than <space> or <newline> can be used instead of a slash to delimit the 
RE and the replacement. Within the RE, the RE delimiter itself can be used as a literal character if 
it is preceded by a backslash. The current line shall be set to the address of the last line on which 
a substitution occurred. 
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An ampersand (' & ') appearing in the replacement shall be replaced by the string matching the 
RE on the current line. The special meaning of ' &' in this context can be suppressed by 
preceding it by backslash. As a more general feature, the characters ' \n', where n is a digit, 
shall be replaced by the text matched by the corresponding back-reference expression. When the 
character ' %' is the only character in the replacement , the replacement used in the most recent 
substitute command shall be used as the replacement in the current substitute command; if there 
was no previous substitute command, the use of ' %' in this manner shall be an error. The ' %' 
shall lose its special meaning when it is in a replacement string of more than one character or is 
preceded by a backslash. For each backslash (' V) encountered in scanning replacement from 
beginning to end, the following character shall lose its special meaning (if any). It is unspecified 
what special meaning is given to any character other than ' &', ' \', ' %', or digits. 

A line can be split by substituting a <newline> character into it. The application shall ensure it 
escapes the <newline> character in the replacement by preceding it by backslash. Such 
substitution cannot be done as part of a g or v command list. The current line number shall be set 
to the address of the last line on which a substitution is performed. If no substitution is 
performed, the current line number shall be unchanged. If a line is split, a substitution shall be 
considered to have been performed on each of the new lines for the purpose of determining the 
new current line number. A substitution shall be considered to have been performed even if the 
replacement string is identical to the string that it replaces. 

The application shall ensure that the value of flags is zero or more of: 

count Substitute for the conntth occurrence only of the RE found on each addressed line. 

g Globally substitute for all non-overlapping instances of the RE rather than just the first 

one. If both g and count are specified, the results are unspecified. 

1 Write to standard output the final line in which a substitution was made. The line shall 

be written in the format specified for the 1 command. 

n Write to standard output the final line in which a substitution was made. The line shall 

be written in the format specified for the n command. 

p Write to standard output the final line in which a substitution was made. The line shall 

be written in the format specified for the p command. 

Copy Command 

Synopsis : (., . ) t address 

The t command shall be equivalent to the m command, except that a copy of the addressed lines 
shall be placed after address address (which can be 0); the current line number shall be set to the 
address of the last line added. 

Undo Command 

Synopsis : u 

The u command shall nullify the effect of the most recent command that modified anything in 
the buffer, namely the most recent a, c, d, g, i, j, m, r, s, t, u, v, G, or V command. All changes 
made to the buffer by a g, G, v, or V global command shall be undone as a single change; if no 
changes were made by the global command (such as with g /RE /p), the u command shall have 
no effect. The current line number shall be set to the value it had immediately before the 
command being undone started. 
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Global Non-Matched Command 

Synopsis: (1, $) v/ RE/command list 

This command shall be equivalent to the global command g except that the lines that are marked 
during the first step shall be those that do not match the RE. 

Interactive Global Not-Matched Command 

Synopsis: (1, $) V/ RE/ 

This command shall be equivalent to the interactive global command G except that the lines that 
are marked during the first step shall be those that do not match the RE. 

Write Command 

Synopsis: (l,$)w [file] 

The w command shall write the addressed lines into the file named by the path name file. The 
command shall create the file, if it does not exist, or shall replace the contents of the existing file. 
The currently remembered path name shall not be changed unless there is no remembered path 
name. If no path name is given, the currently remembered path name, if any, shall be used (see 
the e and f commands); the current line number shall be unchanged. If the command is 
successful, the number of bytes written shall be written to standard output, unless the -s option 
was specified, in the following format: 

"%d\n", <number of bytes written> 

If file begins with ' !', the rest of the line shall be taken to be a shell command line whose 
standard input shall be the addressed lines. Such a shell command line shall not be remembered 
as the current path name. This usage of the write command with ' !' shall not be considered as 
a "last w command that wrote the entire buffer", as described previously; thus, this alone shall 
not prevent the warning to the user if an attempt is made to destroy the editor buffer via the e or 
q commands. 

Line Number Command 

Synopsis: ($) = 

The line number of the addressed line shall be written to standard output in the following 
format: 

"%d\n", <line number> 

The current line number shall be unchanged by this command. 

Shell Escape Command 

Synopsis: ! command 

The remainder of the line after the ' !' shall be sent to the command interpreter to be 
interpreted as a shell command line. Within the text of that shell command line, the unescaped 
character ' %' shall be replaced with the remembered path name; if a ' !' appears as the first 
character of the command, it shall be replaced with the text of the previous shell command 
executed via ' !'. Thus, " ! ! " shall repeat the previous ! command . If any replacements of ' %' or 
' !' are performed, the modified line shall be written to the standard output before command is 
executed. The ' !' command shall write: 

" ! \ n" 
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14370 to standard output upon completion, unless the -s option is specified. The current line number 

14371 shall be unchanged. 

14372 Null Command 

14373 Synopsis: (.+1) 

14374 An address alone on a line shall cause the addressed line to be written. A <newline> character 

14375 alone shall be equivalent to " + lp". The current line number shall be set to the address of the 

14376 written line. 

14377 EXIT STATUS 

14378 The following exit values shall be returned: 

14379 0 Successful completion without any file or command errors. 

14380 >0 An error occurred. 

14381 CONSEQUENCES OF ERRORS 

14382 When an error in the input script is encountered, or when an error is detected that is a 

14383 consequence of the data (not) present in the file or due to an external condition such as a read or 

14384 write error: 

14385 • If the standard input is a terminal device file, all input shall be flushed, and a new command 

14386 read. 

14387 • If the standard input is a regular file, ed shall terminate with a non-zero exit status. 

14388 APPLICATION USAGE 

14389 Because of the extremely terse nature of the default error messages, the prudent script writer 

14390 begins the ed input commands with an H command, so that if any errors do occur at least some 

14391 clue as to the cause is made available. 

14392 In previous versions, an obsolescent - option was described. This is no longer specified. 

14393 Applications should use the -s option. Using - as a file operand now produces unspecified 

14394 results. This allows implementations to continue to support the former required behavior. 

14395 EXAMPLES 

14396 None. 

14397 RATIONALE 

14398 The initial description of this utility was adapted from the SVID. It contains some features not 

14399 found in Version 7 or BSD-derived systems. Some of the differences between the POSIX and 

14400 BSD ed utilities include, but need not be limited to: 

14401 • The BSD - option does not suppress the ' !' prompt after a ! command. 

14402 • BSD does not support the special meanings of the ' %' and ' !' characters within a ! 

14403 command. 

14404 • BSD does not support the addresses ' ;' and '. 

14405 • BSD allows the command/suffix pairs pp, 11, and so on, which are unspecified in this volume 

14406 of IEEE Std. 1003.1-200x. 

14407 • BSD does not support the ' !' character part of the e, r, or w commands. 

14408 • A failed g command in BSD sets the line number to the last line searched if there are no 

14409 matches. 

14410 • BSD does not default the command list to the p command. 
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• BSD does not support the G, h, H, n, or V commands. 

• On BSD, if there is no inserted text, the insert command changes the current line to the 
referenced line -1; that is, the line before the specified line. 

• On BSD, the join command with only a single address changes the current line to that 
address. 

• BSD does not support the P command; moreover, in BSD it is synonymous with the p 
command. 

• BSD does not support the undo of the commands j, m, r, s, or t. 

• The Version 7 ed command W, and the BSD ed commands W, wq, and z are not present in this I 
volume of IEEE Std. 1003.1-200x. 

The -s option was added to allow the functionality of the now withdrawn - option in a manner 
compatible with the Utility Syntax Guidelines. 

In early proposals there was a limit, |ED_FILE_MAX}, that described the historical limitations of 
some ed utilities in their handling of large files; some of these have had problems with files larger 
than 100000 bytes. It was this limitation that prompted much of the desire to include a split 
command in this volume of IEEE Std. 1003.1-200x. Since this limit was removed, this volume of 
IEEE Std. 1003.1-200x requires that implementations document the file size limits imposed by ed 
in the conformance document. The limit |ED_LINE_MAX[ was also removed; therefore, the 
global limit |LINE_MAX} is used for input and output lines. 

The manner in which the 1 command writes non-printable characters was changed to avoid the 
historical backspace-overstrike method. On video display terminals, the overstrike is ambiguous 
because most terminals simply replace overstruck characters, making the 1 format not useful for 
its intended purpose of unambiguously understanding the content of the line. The historical 
backslash escapes were also ambiguous. (The string " a\ 0 011" could represent a line containing 
those six characters or a line containing the three characters ' a', a byte with a binary value of 1, 
and a 1.) In the format required here, a backslash appearing in the line is written as " \ \" so that 
the output is truly unambiguous. The method of marking the ends of lines was adopted from the 
ex editor and is required for any line ending in <space>s; the ' $' is placed on all lines so that a 
real ' $' at the end of a line cannot be misinterpreted. 

Systems with bytes too large to fit into three octal digits must devise other means of displaying 
non-printable characters. Consideration was given to requiring that the number of octal digits be 
large enough to hold a byte, but this seemed to be too confusing for applications on the vast 
majority of systems where three digits are adequate. It would be theoretically possible for the 
application to use the getconf utility to find out the CHAR_BIT value and deal with such an 
algorithm; however, there is really no portable way that an application can use the octal values 
of the bytes across various coded character sets, so the additional specification was not 
worthwhile. 

The description of how a NUL is written was removed. The NUL character cannot be in text 
files, and this volume of IEEE Std. 1003.1-200x should not dictate behavior in the case of 
undefined, erroneous input. 

Unlike some of the other editing utilities, the file names accepted by the E, e, R, and r commands 
are not patterns. 

Early proposals stated that the -p option worked only when standard input was associated with 
a terminal device. This has been changed to conform to historical implementations, thereby 
allowing applications to interpose themselves between a user and the ed utility. 
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14456 The form of the substitute command that uses the n suffix was limited in some historical 

14457 documentation (where this was described incorrectly as "backreferencing"). This limit has been 

14458 omitted because there is no reason an editor processing lines of {LINE_MAX} length should have 

14459 this restriction. The command s/x/X/2 047 should be able to substitute the 2 047th occurrence of x 

14460 on a line. 

14461 The use of printing commands with printing suffixes (such as pn, lp, and so on) was made 

14462 unspecified because BSD-based systems allow this, whereas System V does not. 

14463 Some BSD-based systems exit immediately upon receipt of end-of-file if all of the lines in the file 

14464 have been deleted. Since this volume of IEEE Std. 1003.1-200x refers to the q command in this 

14465 instance, such behavior is not allowed. 

14466 Some historical implementations returned exit status zero even if command errors had occurred; 

14467 this is not allowed by this volume of IEEE Std. 1003.1-200x. 

14468 Some historical implementations contained a bug that allowed a single period to be entered in 

14469 input mode as <backslash> <period> <newline>. This is not allowed by the ed because there is 

14470 no description of escaping any of the characters in input mode; backslashes are entered into the 

14471 buffer exactly as typed. The typical method of entering a single period has been to precede it 

14472 with another character and then use the substitute command to delete that character. 

14473 It is difficult under some modes of some versions of historical operating system terminal drivers 

14474 to distinguish between an end-of-file condition and terminal disconnect. The ISO POSIX-2 

14475 standard does not require implementations to distinguish between the two situations, which 

14476 permits historical implementations of the ed utility on historical platforms to conform. 

14477 Implementations are encouraged to distinguish between the two, if possible, and take 

14478 appropriate action on terminal disconnect. 

14479 Historically, ed accepted a zero address for the a and r commands in order to insert text at the 

14480 start of the edit buffer. When the buffer was empty the command .= returned zero. 

14481 IEEE Std. 1003.1-200x requires conformance to historical practice. 

14482 For consistency with the a and r commands and better user functionality, the i and c commands 

14483 must also accept an address of 0, in which case 0 i is treated as 1 i and likewise for the c 

14484 command. 

14485 All of the following are valid addresses: 

14486 + + + Three lines after the current line. 

14487 /pattern/— One line before the next occurrence of pattern. 

14488 -2 Two lines before the current line. 

14489 3 - 2 Line one (note the intermediate negative address). 

14490 1 2 3 Line six. 

14491 Any number of addresses can be provided to commands taking addresses; for example, 

14492 "1, 2,3,4,5p" prints lines 4 and 5, because two is the greatest valid number of addresses 

14493 accepted by the print command. This, in combination with the semicolon delimiter, permits 

14494 users to create commands based on ordered patterns in the file. For example, the command 

14495 " 3; / f oo /; + 2p " will display the first line after line 3 that contains the pattern foo, plus the next 

14496 two lines. Note that the address " 3 ; " must still be evaluated before being discarded, because 

14497 the search origin for the " / f oo / " command depends on this. 

14498 Historically, ed disallowed address chains, as discussed above, consisting solely of comma or 

14499 semicolon separators; for example, ",,, " or ";;; " were considered an error. For consistency of 

14500 address specification, this restriction is removed. The following table lists some of the address 
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forms now possible: 


Address 

Addrl 

Addr2 

Status 

Comment 

7, 

7 

7 

Historical 


7,5, 

5 

5 

Historical 


7,5, 9 

5 

9 

Historical 


7,9 

7 

9 

Historical 


7 , + 

7 

8 

Historical 


r 

1 

$ 

Historical 


,7 

1 

7 

Extension 


r r 

$ 

$ 

Extension 


r f 

$ 

$ 

Extension 


7; 

7 

7 

Historical 


7; 5; 

5 

5 

Historical 


7; 5 ; 9 

5 

9 

Historical 


7; 5, 9 

5 

9 

Historical 


7;$;4 

$ 

4 

Historical 

Valid, but erroneous. 

7 ; 9 

7 

9 

Historical 


7 ; + 

7 

8 

Historical 


r 


$ 

Historical 


; 7 


7 

Extension 


t r 

$ 

$ 

Extension 


t r 

$ 

$ 

Extension 



Historically, values could be added to addresses by including them after one or more <blank> 
characters; for example, "3 - 5p" wrote the seventh line of the file, and "/foo/ 5" was the 
same as "5 /foo/". However, only absolute values could be added; for example, " 5 /foo/" 
was an error. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, ed accepted the ' '' character as an address, in which case it was identical to the 
hyphen character. IEEE Std. 1003.1-200x does not require or prohibit this behavior. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

ex, sed, sh, vi 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

In the OPTIONS section, the meaning of -s and - is clarified. 

Second FUTURE DIRECTION added. 

Issue 6 

The obsolescent single-minus form has been removed. 

A second APPLICATION USAGE note has been added. 

The Open Group corrigenda item U025/2 has been applied, correcting the description of the Edit 
section. 
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14545 

14546 

14547 

14548 
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The ed utility is updated to align with the IEEE P1003.2b draft standard. This includes addition of I 
the treatment of the SIGQUIT signal, changes to ed addressing, changes to processing when I 
end-of-file is detected and when terminal disconnect is detected. I 

The normative text is reworded to avoid use of the term "must” for application requirements. I 
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NAME 

env — set the environment for command invocation 

SYNOPSIS 

env [—i ][name=value]... [utility [argument...]] 

DESCRIPTION 

The env utility shall obtain the current environment, modify it according to its arguments, then 

invoke the utility named by the utility operand with the modified environment. 

Optional arguments shall be passed to utility. 

If no utility operand is specified, the resulting environment shall be written to the standard 

output, with one name=valne pair per line. 

OPTIONS 

The env utility shall conform to the System Interface Definitions volume of I 

IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-i Invoke utility with exactly the environment specified by the arguments; the 

inherited environment shall be ignored completely. 

OPERANDS 

The following operands shall be supported: 

name=value Arguments of the form name=value shall modify the execution environment, and 
shall be placed into the inherited environment before the utility is invoked. 

utility The name of the utility to be invoked. If the utility operand names any of the 

special built-in utilities in Section 2.14 on page 96, the results are undefined. 

argument A string to pass as an argument for the invoked utility. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of env: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 
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14591 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

14592 PATH Determine the location of the utility, as described in the System Interface I 

14593 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. If I 

14594 PATH is specified as a name=value operand to env, the value given shall be used in 

14595 the search for utility. 

14596 ASYNCHRONOUS EVENTS 

14597 Default. 

14598 STDOUT 

14599 If no utility operand is specified, each name-value pair in the resulting environment shall be 

14600 written in the form: 

14601 "%s=%s\n", <name>, <value> 

14602 If the utility operand is specified, the env utility shall not write to standard output. 

14603 STDERR 

14604 Used only for diagnostic messages. 

14605 OUTPUT FILES 

14606 None. 

14607 EXTENDED DESCRIPTION 

14608 None. 

14609 EXIT STATUS 

14610 If the utility utility is invoked, the exit status of env shall be the exit status of utility; otherwise, 

14611 the env utility shall exit with one of the following values: 

14612 0 The env utility completed successfully. 

14613 1-125 An error occurred in the env utility. 

14614 126 The utility specified by utility was found but could not be invoked. 

14615 127 The utility specified by utility could not be found. 

14616 CONSEQUENCES OF ERRORS 

14617 Default. 

14618 APPLICATION USAGE 

14619 The command, env, nice, nohup, time, and xargs utilities have been specified to use exit code 127 if 

14620 an error occurs so that applications can distinguish "failure to find a utility" from "invoked 

14621 utility exited with an error indication". The value 127 was chosen because it is not commonly 

14622 used for other meanings; most utilities use small values for "normal error conditions" and the 

14623 values above 128 can be confused with termination due to receipt of a signal. The value 126 was 

14624 chosen in a similar manner to indicate that the utility could be found, but not invoked. Some 

14625 scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction 

14626 between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 

14627 exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 

14628 any other reason. 

14629 Historical implementations of the env utility use the execvp( ) or execlp( ) functions defined in the 

14630 System Interfaces volume of IEEE Std. 1003.1-200x to invoke the specified utility; this provides 

14631 better performance and keeps users from having to escape characters with special meaning to 

14632 the shell. Therefore, shell functions, special built-ins, and built-ins that are only provided by the 

14633 shell are not found. 
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14634 EXAMPLES 

14635 The following command: 

14636 env —i PATH=/mybin mygrep xyz myfile 

14637 invokes the command mygrep with a new PATH value as the only entry in its environment. In 

14638 this case, PATH is used to locate mygrep, which then must reside in /mybin. 

14639 RATIONALE 

14640 As with all other utilities that invoke other utilities, this volume of IEEE Std. 1003.1-200x only 

14641 specifies what env does with standard input, standard output, standard error, input files, and 

14642 output files. If a utility is executed, it is not constrained by the specification of input and output 

14643 by env. 

14644 The -i option was added to allow the functionality of the withdrawn - option in a manner 

14645 compatible with the Utility Syntax Guidelines. 

14646 Some have suggested that env is redundant since the same effect is achieved by: 

14647 name=value . . . utility [ argument ... ] 

14648 The example is equivalent to env when an environment variable is being added to the 

14649 environment of the command, but not when the environment is being set to the given value. 

14650 The env utility also writes out the current environment if invoked without arguments. There is 

14651 sufficient functionality beyond what the example provides to justify inclusion of env. 

14652 FUTURE DIRECTIONS 

14653 None. 

14654 SEE ALSO 

14655 Section 2.5 on page 43 

14656 CHANGE HISTORY 

14657 First released in Issue 2. 

14658 Issue 4 

14659 Aligned with the ISO/IEC 9945-2:1993 standard. 
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NAME 

ex — text editor 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

This page has undergone significant revision due to the 1003.2b merger. The following D1 XCU I 
ERNs should be reviewed now the merge is complete: 234-239, 241-245. I 

SYNOPSIS 

UP ex [—rR][-1][—s | —v][—c command]-t tagstring] [-w size][file ...] I 

DESCRIPTION 

The ex utility is a line-oriented text editor. There are two other modes of the editor—open and I 
visual—in which screen-oriented editing is available. This is described more fully by the ex open I 
and visual commands and in vi. I 

This section uses the term edit buffer to describe the current working text. No specific I 
implementation is implied by this term. All editing changes are performed on the edit buffer, I 
and no changes to it shall affect any file until an editor command writes the file. I 

Certain terminals do not have all the capabilities necessary to support the complete ex definition, I 
such as the full-screen editing commands ( visual mode or open mode). When these commands I 
cannot be supported on such terminals, this condition shall not produce an error message such 
as "not an editor command" or report a syntax error. The implementation may either accept the I 
commands and produce results on the screen that are the result of an unsuccessful attempt to I 
meet the requirements of this volume of IEEE Std. 1003.1-200x or report an error describing the I 
terminal-related deficiency. I 

OPTIONS 

The ex utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-c command Specify an initial command to be executed in the first edit buffer loaded from an I 
existing file (see the EXTENDED DESCRIPTION section). Implementations may I 
support more than a single -c option. In such implementations, the specified I 
commands shall be executed in the order specified on the command line. I 

man -1 (The letter ell.) Set lisp mode; indents appropriately for Lisp code; the (), {}, [[, and I 

]] commands in visual mode are modified to have meaning for Lisp. I 

-r Recover the named files (see the EXTENDED DESCRIPTION section). Recovery I 

information for a file shall be saved during an editor or system crash (for example, I 
when the editor is terminated by a signal which the editor can catch), or after the I 
use of an ex preserve command. I 

A crash in this context is an unexpected failure of the system or utility that requires I 
restarting the failed system or utility. A system crash implies that any utilities 
running at the time also crash. In the case of an editor or system crash, the number I 
of changes to the edit buffer (since the most recent preserve command) that will be I 
recovered is unspecified. I 

If no file operands are given and the -t option is not specified, all other options, the I 
EXINIT variable, and any .exrc files shall be ignored; a list of all recoverable files I 
available to the invoking user shall be written, and the editor shall exit normally I 
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without further action. I 

-R Set readonly edit option. I 

-s Prepare ex for batch use by taking the following actions: 

• Suppress writing prompts and informational (but not diagnostic) messages. 

• Ignore the value of TERM and any implementation default terminal type and 

assume the terminal is a type incapable of supporting open or visual modes; I 
see the visual command and the description of vi. I 

• Suppress the use of the EXINIT environment variable and the reading of any 

.exrc file; see the EXTENDED DESCRIPTION section. I 

• Suppress autoindentation, ignoring the value of the autoindent edit option. I 

-t tagstring Edit the file containing the specified tagstring; see ctags. The tags feature I 
represented by -t tagstring and the tag command is optional. It shall be provided I 
on any system that also provides a conforming implementation of ctags; otherwise, I 
the use of -t produces undefined results. On any system, it shall be an error to I 
specify more than a single -t option. I 

-v Begin in visual mode (see vi). I 

-w size Set the value of the window editor option to size. 

OPERANDS I 

The following operand shall be supported: 

file A path name of a file to be edited. 

STDIN 

The standard input consists of a series of commands and input text, as described in the I 
EXTENDED DESCRIPTION section. The implementation may limit each line of standard input I 
to a length of |LINE_MAX}. I 

If the standard input is not a terminal device, it shall be as if the -s option had been specified. I 

If a read from the standard input returns an error, or if the editor detects an end-of-file condition I 
from the standard input, it shall be equivalent to a SIGHUP asynchronous event. I 

INPUT FILES 

Input files shall be text files or files that would be text files except for an incomplete last line that I 
is not longer than |LINE_MAX}-1 bytes in length and contains no NUL characters. By default, I 
any incomplete last line shall be treated as if it had a trailing <newline> character. The editing of I 
other forms of files may optionally be allowed by ex implementations. I 

The .exrc files and source files shall be text files consisting of ex commands; see the EXTENDED I 
DESCRIPTION section. I 

By default, the editor shall read lines from the files to be edited without interpreting any of those I 
lines as any form of editor command. I 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of ex: 

COLUMNS Override the system-selected horizontal screen size. See the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for I 
valid values and results when it is unset or null. 
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14747 

EXINIT 

Determine a list of ex commands that are executed on editor start-up. See the 
EXTENDED DESCRIPTION section for more details of the initialization phase. 

14748 

14749 

HOME 

Determine a path name of a directory that shall be searched for an editor start-up 
file named .exrc; see the EXTENDED DESCRIPTION section. 

14750 

14751 

14752 

14753 

14754 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

14755 

14756 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

14757 

14758 

14759 

LCJZOLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements within regular expressions. 

14760 

14761 

14762 

14763 

14764 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the behavior of character classes within regular 
expressions, the classification of characters as uppercase or lowercase letters, the 
case conversion of letters, and the detection of word boundaries. 

14765 

14766 

14767 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

14768 

14769 

14770 

14771 

LINES 

Override the system-selected vertical screen size, used as the number of lines in a 
screenful and the vertical screen size in visual mode. See the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for 
valid values and results when it is unset or null. 

14772 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

14773 

14774 

14775 

PATH 

Determine the search path for the shell command specified in the ex editor 
commands !, shell, read, and write, and the open and visual mode command !; see 
the description of command search and execution in Section 2.9.1.1 on page 69. 

14776 

14777 

SHELL 

Determine the preferred command line interpreter for use as the default value of 
the shell edit option. 

14778 

14779 

TERM 

Determine the name of the terminal type. If this variable is unset or null, an 
unspecified default terminal type shall be used. 

14780 ASYNCHRONOUS EVENTS 

14781 The following symbol is used in this and following sections to specify command and 

14782 asynchronous event actions: 

14783 

14784 

14785 

14786 

14787 

14788 

complete write 

A complete write is a write of the entire contents of the edit buffer to a file of a type 
other than a terminal device, or the saving of the edit buffer caused by the user 
executing the ex preserve command. Writing the contents of the edit buffer to a 
temporary file that will be removed when the editor exits shall not be considered a 
complete write. 

14789 

The following actions shall be taken upon receipt of signals: 
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14790 

14791 

14792 

14793 

14794 


SIGINT If the standard input is not a terminal device, ex shall not write the file or return to 
command or text input mode, and shall exit with a non-zero exit status. 

Otherwise, if executing an open or visual text input mode command, ex in receipt 
of SIGINT shall behave identically to its receipt of the <ESC> character. 

Otherwise: 


14795 

14796 

14797 


1. If executing an ex text input mode command, all input lines that have been 
completely entered shall be resolved into the edit buffer, and any partially 
entered line shall be discarded. 


14798 

14799 

14800 

14801 

14802 


2. If there is a currently executing command, it shall be aborted and a message 
displayed. Unless otherwise specified by the ex or vi command descriptions, 
it is unspecified whether any lines modified by the executing command 
appear modified, or as they were before being modified by the executing 
command, in the buffer. 


14803 

14804 


If the currently executing command was a motion command, its associated 
command shall be discarded. 


14805 

14806 


3. If in open or visual command mode, the terminal shall be alerted. 

4. The editor shall then return to command mode. 


14807 

14808 

14809 

14810 

14811 


SIGCONT The screen shall be refreshed if in open or visual mode. 

SIGHUP If the edit buffer has been modified since the last complete write, ex shall attempt 
to save the edit buffer so that it can be recovered later using the -r option or the ex 
recover command. The editor shall not write the file or return to command or text 
input mode, and shall terminate with a non-zero exit status. 


14812 SIGTERM Refer to SIGHUP. 


14813 The action taken for all other signals is unspecified. 

14814 STDOUT 

14815 The standard output shall be used only for writing prompts to the user, for informational I 

14816 messages, and for writing lines from the file. I 

14817 STDERR 

14818 Used only for diagnostic messages. 

14819 OUTPUT FILES 

14820 The output from ex shall be text files. I 

14821 EXTENDED DESCRIPTION 

14822 Only the ex mode of the editor is described in this section. See vi for additional editing I 

14823 capabilities available in ex. I 

14824 When an error occurs, ex shall write a message. If the terminal supports a standout mode (such I 

14825 as inverse video), the message shall be written in standout mode. If the terminal does not I 

14826 support a standout mode, and the edit option errorbells is set, an alert action shall precede the I 

14827 error message. I 

14828 By default, ex shall start in command mode, which shall be indicated by a : prompt; see the I 

14829 prompt command. Text input mode can be entered by the append, insert, or change commands; I 

14830 it can be exited (and command mode re-entered) by typing a period (' .') alone at the beginning I 

14831 of a line. I 
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Initialization in ex and vi 

The following symbols are used in this and following sections to specify locations in the edit 
buffer: 

alternate and current path names 

Two path names, named current and alternate, are maintained by the editor. Any ex 
commands that take file names as arguments shall set them as follows: 

1. If a file argument is specified to the ex edit, ex, or recover commands, or if an ex tag 
command replaces the contents of the edit buffer. 

a. If the command replaces the contents of the edit buffer, the current path name 
shall be set to the file argument or the file indicated by the tag, and the alternate 
path name shall be set to the previous value of the current path name. 

b. Otherwise, the alternate path name shall be set to the file argument. 

2. If a file argument is specified to the ex next command: 

a. If the command replaces the contents of the edit buffer, the current path name 
shall be set to the first file argument, and the alternate path name shall be set to 
the previous value of the current path name. 

3. If a file argument is specified to the ex file command, the current path name shall be 
set to the file argument, and the alternate path name shall be set to the previous value 
of the current path name. 

4. If a file argument is specified to the ex read and write commands (that is, when 
reading or writing a file, and not to the program named by the shell edit option), or a 
file argument is specified to the ex xit command: 

a. If the current path name has no value, the current path name shall be set to the 
file argument. 

b. Otherwise, the alternate path name shall be set to the file argument. 

If the alternate path name is set to the previous value of the current path name when the 
current path name had no previous value, then the alternate path name shall have no value 
as a result. 

current line 

The line of the edit buffer referenced by the cursor. Each command description specifies the 
current line after the command has been executed, as the current line value. When the edit 
buffer contains no lines, the current line shall be zero; see Addressing in ex on page 394. 

current column 

The current screen column occupied by the cursor. (The columns shall be numbered 
beginning at 1.) Each command description specifies the current column after the command 
has been executed, as the current column value. This column is an ideal column that is 
remembered over the lifetime of the editor. The actual screen column upon which the cursor 
rests may be different from the current column; see the cursor positioning discussion in 
Command Descriptions in vi on page 1031. 

set to non-<blank> 

A description for a current column value, meaning that the current column shall be set to 
the last screen column on which is displayed any part of the first non-<blank> character of 
the line. If the line has no non-<blank> characters, the current column shall be set to the last 
screen column on which is displayed any part of the last character in the line. If the line is 
empty, the current column shall be set to column position 1. 


392 


Technical Standard (2000) (Draft February 29, 2000) 




14877 

14878 

14879 

14880 

14881 

14882 

14883 

14884 

14885 

14886 

14887 

14888 

14889 

14890 

14891 

14892 

14893 

14894 

14895 

14896 

14897 

14898 

14899 

14900 

14901 

14902 

14903 

14904 

14905 

14906 

14907 

14908 

14909 

14910 

14911 

14912 

14913 

14914 

14915 

14916 

14917 


Utilities 


ex 


The length of lines in the edit buffer may be limited to |LINE_MAX} bytes. In open and visual 
mode, the length of lines in the edit buffer may be limited to the number of characters that will 
fit in the display. If either limit is exceeded during editing, an error message shall be written. If 
either limit is exceeded by a line read in from a file, an error message shall be written and the 
edit session may be terminated. 

If the editor stops running due to any reason other than a user command, and the edit buffer has 
been modified since the last complete write, it shall be equivalent to a SIGHUP asynchronous 
event. If the system crashes, it shall be equivalent to a SIGHUP asynchronous event. 

During initialization (before the first file is copied into the edit buffer or any user commands 
from the terminal are processed) the following shall occur: 

1. If the environment variable EXINIT is set, the editor shall execute the ex commands 
contained in that variable. 

2. If the EXINIT variable is not set, and all of the following are true: 

a. The HOME environment variable is not null and not empty. 

b. The file .exrc in the directory referred to by the HOME environment variable: 

1. Exists 

2. Is owned by the same user ID as the real user ID of the process or the process 
has appropriate privileges 

3. Is not writeable by anyone other than the owner 

The editor shall execute the ex commands contained in that file. 

3. If and only if all the following are true: 

a. The current directory is not referred to by the HOME environment variable. 

b. A command in the EXINIT environment variable or a command in the .exrc file in the 
directory referred to by the HOME environment variable sets the editor option exrc. 

c. The .exrc file in the current directory: 

1. Exists 

2. Is owned by the same user ID as the real user ID of the process, or by one of a 
set of implementation-dependent user IDs 

3. Is not writeable by anyone other than the owner 

The editor shall attempt to execute the ex commands contained in that file. 

Lines in any .exrc file that contain no characters or only <blank> characters shall be ignored. If 
any .exrc file exists, but is not read for ownership or permission reasons, it shall be an error. 

After the EXINIT variable and any .exrc files are processed, the first file specified by the user 
shall be edited, as follows: 

1. If the user specified the -t option, the effect shall be as if the ex tag command was entered 
with the specified argument, with the exception that if tag processing does not result in a 
file to edit, the effect shall be as described in step 3. below. 

2. Otherwise, if the user specified any command line file arguments, the effect shall be as if 
the ex edit command was entered with the first of those arguments as its file argument. 

3. Otherwise, the effect shall be as if the ex edit command was entered with a nonexistent file 
name as its file argument. It is unspecified whether this action shall set the current path 


Commands and Utilities, Issue 6 


393 




14918 

14919 

14920 

14921 

14922 

14923 

14924 

14925 

14926 

14927 

14928 

14929 

14930 

14931 

14932 

14933 

14934 

14935 

14936 

14937 

14938 

14939 

14940 

14941 

14942 

14943 

14944 

14945 

14946 

14947 

14948 

14949 

14950 

14951 

14952 

14953 

14954 

14955 

14956 

14957 

14958 

14959 

14960 

14961 

14962 

14963 


ex 


Utilities 


name. In an implementation where this action does not set the current path name, any 
editor command using the current path name shall fail until an editor command sets the 
current path name. 

If the -r option was specified, the first time a file in the initial argument list or a file specified by 
the -t option is edited, if recovery information has previously been saved about it, that 
information shall be recovered and the editor shall behave as if the contents of the edit buffer 
have already been modified. If there are multiple instances of the file to be recovered, the one 
most recently saved shall be recovered, and an informational message that there are previous 
versions of the file that can be recovered shall be written. If no recovery information about a file 
is available, an informational message to this effect shall be written, and the edit shall proceed as 
usual. 

If the - option was specified, the first time a file that already exists (including a file that might 
not exist but for which recovery information is available, when the -r option is specified) 
replaces or initializes the contents of the edit buffer, the current line shall be set to the last line of 
the edit buffer, the current column shall be set to non-<blank>, and the ex commands specified 
with the -c option shall be executed. In this case, the current line and current column shall not be 
set as described for the command associated with the replacement or initialization of the edit 
buffer contents. However, if the -t option or a tag command is associated with this action, the -c 
option commands shall be executed and then the movement to the tag shall be performed. 

The current argument list shall initially be set to the file names specified by the user on the 
command line. If no file names are specified by the user, the current argument list shall be 
empty. If the -t option was specified, it is unspecified whether any file name resulting from tag 
processing shall be prepended to the current argument list. In the case where the file name is 
added as a prefix to the current argument list, the current argument list reference shall be set to 
that file name. In the case where the file name is not added as a prefix to the current argument 
list, the current argument list reference shall logically be located before the first of the file names 
specified on the command line (for example, a subsequent ex next command shall edit the first 
file name from the command line). If the -t option was not specified, the current argument list 
reference shall be to the first of the file names on the command line. 

Addressing in ex 

Addressing in ex relates to the current line and the current column; the address of a line is its 1- 
based line number, the address of a column is its 1-based count from the beginning of the line. 
Generally, the current line is the last line affected by a command. The current line number is the 
address of the current line. In each command description, the effect of the command on the 
current line number and the current column is described. 

Addresses are constructed as follows: 

1. The character ' .' (period) shall address the current line. 

2. The character ' $' shall address the last line of the edit buffer. 

3. The positive decimal number n shall address the nth line of the edit buffer. 

4. The address "' x " refers to the line marked with the mark name character ' x', which shall 
be a lowercase letter from the portable character set or one of the characters ' '' or ''' . It 
shall be an error if the line that was marked is not currently present in the edit buffer or the 
mark has not been set. Lines can be marked with the ex mark or k commands, or the vi m 
command. 

5. A regular expression (RE) enclosed by slashes (' /') shall address the first line found by 
searching forwards from the line following the current line toward the end of the edit 
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buffer and stopping at the first line containing a string matching the regular expression. As 
stated in Regular Expressions in ex on page 424, an address consisting of a null regular 
expression delimited by slashes " / / " shall address the next line containing the last regular 
expression encountered. In addition, the second slash can be omitted at the end of a 
command line. If the wrapscan edit option is set, the search shall wrap around to the 
beginning of the edit buffer and continue up to and including the current line, so that the 
entire edit buffer is searched. Within the regular expression, the sequence "\/" shall 
represent a literal slash instead of the regular expression delimiter. 

6. A regular expression enclosed in question marks (' ?') shall address the first line found by 
searching backwards from the line preceding the current line toward the beginning of the 
edit buffer and stopping at the first line containing a string matching the regular 
expression. The second question mark can be omitted at the end of a command line. If the 
wrapscan edit option is set, the search shall wrap around from the beginning of the edit 
buffer to the end of the edit buffer and continue up to and including the current line, so 
that the edit entire buffer is searched. Within the regular expression, the sequence " \ ?" 
shall represent a literal question mark instead of the RE delimiter. 

7. A plus sign (' + ') or a minus sign (' —') followed by a decimal number shall address the 
current line plus or minus the number. A ' + ' or not followed by a decimal number 
shall address the current line plus or minus 1. 

Addresses can be followed by zero or more address offsets, optionally <blank> character- 
separated. Address offsets are constructed as follows: 

1. A '+' or 'immediately followed by a decimal number shall add (subtract) the 
indicated number of lines to (from) the address. A ' + ' or not followed by a decimal 
number shall add (subtract) 1 to (from) the address. 

2. A decimal number shall add the indicated number of lines to the address. 

It shall not be an error for an intermediate address value to be less than zero or greater than the 
last line in the edit buffer. It shall be an error for the final address value to be less than zero or 
greater than the last line in the edit buffer. 

Commands take zero, one, or two addresses; see the descriptions of lnddr and 2nddr in 
Command Descriptions in ex on page 401. If more than the required number of addresses are 
provided to a command that requires zero addresses, it shall be an error. Otherwise, if more than 
the required number of addresses are provided to a command, the addresses specified first shall 
be evaluated and then discarded until the maximum number of valid addresses remain. 

Addresses shall be separated from each other by a comma (' , ') or a semicolon (';'). If no 
address is specified before or after a comma or semicolon separator, it shall be as if the address 
of the current line was specified before or after the separator. In the case of a semicolon 
separator, the current line (' .') shall be set to the first address, and only then will the next 
address be calculated. This feature can be used to determine the starting line for forwards and 
backwards searches (see rules 5. and 6.). 

A percent sign (' %') shall be equivalent to entering the two addresses " 1, $". 

Any delimiting <blank> characters between addresses, address separators, or address offsets 
shall be discarded. 
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Command Line Parsing in ex 

The following symbol is used in this and following sections to describe parsing behavior: 

escape If a character is referred to as "backslash escaped" or "<control>-V escaped," it 

shall mean that the character acquired or lost a special meaning by virtue of being 
preceded, respectively, by a backslash or <control>-V character. Unless otherwise 
specified, the escaping character shall be discarded at that time and shall not be 
further considered for any purpose. 

Command-line parsing shall be done in the following steps. For each step, characters already 
evaluated shall be ignored; that is, the phrase "leading character" refers to the next character 
that has not yet been evaluated. 

1. Leading colon characters shall be skipped. 

2. Leading <blank> characters shall be skipped. 

3. If the leading character is a double-quote character, the characters up to and including the 
next non-backslash-escaped <newline> character shall be discarded, and any subsequent 
characters shall be parsed as a separate command. 

4. Leading characters that can be interpreted as addresses shall be evaluated; see Addressing 
in ex on page 394. 

5. Leading <blank> characters shall be skipped. 

6. If the next character is a vertical-line character or a <newline> character: 

a. If the next character is a <newline> character: 

1. li ex is in open or visual mode, the current line shall be set to the last address 
specified, if any. 

2. Otherwise, if the last command was terminated by a vertical-line character, no 
action shall be taken; for example, the command "] |<newline>" shall 
execute two implied commands, not three. 

3. Otherwise, step 6.b. shall apply. 

b. Otherwise, the implied command shall be the print command. The last #, p, and 1 
flags specified to any ex command shall be remembered and shall apply to this 
implied command. Executing the ex number, print, or list command shall set the 
remembered flags to #, nothing, and 1, respectively, plus any other flags specified for 
that execution of the number, print, or list command. 

If ex is not currently performing a global or v command, and no address or count is 
specified, the current line shall be incremented by 1 before the command is executed. 
If incrementing the current line would result in an address past the last line in the 
edit buffer, the command shall fail, and the increment shall not happen. 

c. The <newline> character or vertical-line character shall be discarded and any 
subsequent characters shall be parsed as a separate command. 

7. The command name shall be comprised of the next character (if the character is not 
alphabetic), or the next character and any subsequent alphabetic characters (if the 
character is alphabetic), with the following exceptions: 

a. Commands that consist of any prefix of the characters in the command name delete, 
followed immediately by any of the characters 1, p, +, -, or # shall be interpreted as a 
delete command, followed by a <blank> character, followed by the characters that 
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were not part of the prefix of the delete command. The maximum number of 
characters shall be matched to the command name delete; for example, "del" shall 
not be treated as " de " followed by the flag 1. 

b. Commands that consist of the character k, followed by a character that can be used 
as the name of a mark, shall be equivalent to the mark command followed by a 
<blank> character, followed by the character that followed the k. 

c. Commands that consist of the character s, followed by characters that could be 
interpreted as valid options to the s command, shall be the equivalent of the s 
command, without any pattern or replacement values, followed by a <blank> 
character, followed by the characters after the s. 

8. The command name shall be matched against the possible command names, and a 
command name that contains a prefix matching the characters specified by the user shall 
be the executed command. In the case of commands where the characters specified by the 
user could be ambiguous, the executed command shall be as follows: 


a 

append 

n 

next 

t 

t 

c 

change 

p 

print 

u 

undo 

ch 

change 

pr 

print 

un 

undo 

e 

edit 

r 

read 

V 

V 

m 

move 

re 

read 

w 

write 

ma 

mark 

s 

s 




Implementation extensions with names causing similar ambiguities shall not be checked 
for a match until all possible matches for commands specified by IEEE Std. 1003.1-200x 
have been checked. 

9. If the command is a ! command, or if the command is a read command followed by zero 
or more <blank> characters and a !, or if the command is a write command followed by 
one or more <blank> characters and a !, the rest of the command shall include all 
characters up to a non-backslash-escaped <newline> character. The <newline> character 
shall be discarded and any subsequent characters shall be parsed as a separate ex 
command. 

10. Otherwise, if the command is an edit, ex, or next command, or a visual command while in 
open or visual mode, the next part of the command shall be parsed as follows: 

a. Any ' !' character immediately following the command shall be skipped and be part 
of the command. 

b. Any leading <blank> characters shall be skipped and be part of the command. 

c. If the next character is a '+', characters up to the first non-backslash-escaped 
<newline> character or non-backslash-escaped <blank> character shall be skipped 
and be part of the command. 

d. The rest of the command shall be determined by the steps specified in paragraph 12. 

11. Otherwise, if the command is a global, open, s, or v command, the next part of the 
command shall be parsed as follows: 

a. Any leading <blank> characters shall be skipped and be part of the command. 

b. If the next character is not an alphanumeric, double-quote, <newline>, backslash, or 
vertical-line character: 

1. The next character shall be used as a command delimiter. 
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2. If the command is a global, open, or v command, characters up to the first 
non-backslash-escaped <newline> character, or first non-backslash-escaped 
delimiter character, shall be skipped and be part of the command. 

3. If the command is an s command, characters up to the first non-backslash- 
escaped <newline> character, or second non-backslash-escaped delimiter 
character, shall be skipped and be part of the command. 

c. If the command is a global or v command, characters up to the first non-backslash- 
escaped <newline> character shall be skipped and be part of the command. 

d. Otherwise, the rest of the command shall be determined by the steps specified in 
paragraph 12. 

12. Otherwise: 

a. If the command was a map, unmap, abbreviate, or unabbreviate command, 
characters up to the first non-<control>-V-escaped <newline>, vertical-line, or 
double-quote character shall be skipped and be part of the command. 

b. Otherwise, characters up to the first non-backslash-escaped <newline>, vertical-line, 
or double-quote character shall be skipped and be part of the command. 

c. If the command was an append, change, or insert command, and the step 12.b. 
ended at a vertical-line character, any subsequent characters, up to the next non- 
backslash-escaped <newline> character shall be used as input text to the command. 

d. If the command was ended by a double-quote character, all subsequent characters, 
up to the next non-backslash-escaped <newline> character, shall be discarded. 

e. The terminating <newline> or vertical-line character shall be discarded and any 
subsequent characters shall be parsed as a separate ex command. 

Command arguments shall be parsed as described by the Synopsis and Description of each 
individual ex command. This parsing shall not be <blank> character-sensitive, except for the ! 
argument, which must follow the command name without intervening <blank> characters, and 
where it would otherwise be ambiguous. For example, count and flag arguments need not be 
<blank> character separated because "d22p" is not ambiguous, but file arguments to the ex next 
command must be separated by one or more <blank> characters. Any <blank> character in 
command arguments for the abbreviate, unabbreviate, map, and unmap commands can be 
<control>-V-escaped, in which case the <blank> character shall not be used as an argument 
delimiter. Any <blank> character in the command argument for any other command can be 
backslash-escaped, in which case that <blank> character shall not be used as an argument 
delimiter. 

Within command arguments for the abbreviate, unabbreviate, map, and unmap commands, 
any character can be <control>-V-escaped. All such escaped characters shall be treated literally 
and shall have no special meaning. Within command arguments for all other ex commands that 
are not regular expressions or replacement strings, any character that would otherwise have a 
special meaning can be backslash-escaped. Escaped characters shall be treated literally, without 
special meaning as shell expansion characters or ' !', ' %', and ' #' expansion characters. See 
Regular Expressions in ex on page 424 and Replacement Strings in ex on page 425 for 
descriptions of command arguments that are regular expressions or replacement strings. 

Non-backslash-escaped ' %' characters appearing in file arguments to any ex command shall be 
replaced by the current path name; unescaped ' #' characters shall be replaced by the alternate 
path name. It shall be an error if ' %' or ' #' characters appear unescaped in an argument and 
their corresponding values are not set. 
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Non-backslash-escaped ' !' characters in the arguments to either the ex ! command or the open 
and visual mode ! command, or in the arguments to the ex read command, where the first non- 
<blank> character after the command name is a ' ! ' character, or in the arguments to the ex 
write command where the command name is followed by one or more <blank> characters and 
the first non-<blank> character after the command name is a ' !' character, shall be replaced 
with the arguments to the last of those three commands as they appeared after all unescaped 
' %', ' #', and ' !' characters were replaced. It shall be an error if ' !' characters appear 
unescaped in one of these commands and there has been no previous execution of one of these 
commands. 

If an error occurs during the parsing or execution of an ex command: 

• An informational message to this effect shall be written. Execution of the ex command shall 
stop, and the cursor (for example, the current line and column) shall not be further modified. 

• If the ex command resulted from a map expansion, all characters from that map expansion 
shall be discarded, except as otherwise specified by the map command. 

• Otherwise, if the ex command resulted from the processing of an EXINIT environment 
variable, a .exrc file, a :source command, a -c option, or a +command specified to an ex edit, 
ex, next, or visual command, no further commands from the source of the commands shall 
be executed. 

• Otherwise, if the ex command resulted from the execution of a buffer or a global or v 
command, no further commands caused by the execution of the buffer or the global or v 
command shall be executed. 

• Otherwise, if the ex command was not terminated by a <newline> character, all characters up 
to and including the next non-backslash-escaped <newline> character shall be discarded. 

Input Editing in ex 

The following symbols are used in this and following sections to specify command actions. 

word In the POSIX locale, a word consists of a maximal sequence of letters, digits, and 

underscores, delimited at both ends by characters other than letters, digits, or 
underscores, or by the beginning or end of a line or the edit buffer. 

When accepting input characters from the user, in either ex command mode or ex text input 
mode, ex shall enable canonical mode input processing, as defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x. 

If in ex text input mode: 

1. If the number edit option is set, ex shall prompt for input using the line number that would 
be assigned to the line if it is entered, in the format specified for the ex number command. 

2. If the autoindent edit option is set, ex shall prompt for input using autoindent characters, 
as described by the autoindent edit option, autoindent characters shall follow the line 
number, if any. 

If in ex command mode: 

1. If the prompt edit option is set, input shall be prompted for using a single ' :' character; 
otherwise, there shall be no prompt. 

The input characters in the following sections shall have the following effects on the input line. 
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Scroll 

Synopsis: eof 

See the description of the stty eof character in stty. 

If in ex command mode: 

If the eof character is the first character entered on the line, the line shall be evaluated as if it 
contained two characters: a <control>-D and a <newline> character. 

Otherwise, the eof character shall have no special meaning. 

If in ex text input mode: 

If the cursor follows an autoindent character, the autoindent characters in the line shall be 
modified so that a part of the next text input character will be displayed on the first column 
in the line after the previous shiftwidth edit option column boundary, and the user shall be 
prompted again for input for the same line. 

Otherwise, if the cursor follows a ' 0', which follows an autoindent character, and the ' 0 ' 
was the previous text input character, the ' 0' and all autoindent characters in the line shall 
be discarded, and the user shall be prompted again for input for the same line. 

Otherwise, if the cursor follows a ' "', which follows an autoindent character, and the ' "' 
was the previous text input character, the ' '' and all autoindent characters in the line shall 
be discarded, and the user shall be prompted again for input for the same line. In addition, 
the autoindent level for the next input line shall be derived from the same line from which 
the autoindent level for the current input line was derived. 

Otherwise, if there are no autoindent or text input characters in the line, the eof character 
shall be discarded. 

Otherwise, the eof character shall have no special meaning. 


<newline> 

Synopsis: <newline> 

<control>-J 

If in ex command mode: 

Cause the command line to be parsed; <control>-J shall be mapped to the <newline> 
character for this purpose. 

If in ex text input mode: 

Terminate the current line. If there are no characters other than autoindent characters on the 
line, all characters on the line shall be discarded. 

Prompt for text input on a new line after the current line. If the autoindent edit option is set, 
an appropriate number of autoindent characters shall be added as a prefix to the line as 
described by the ex autoindent edit option. 
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<backslash> 

Synopsis: <backslash> 

Allow the entry of a subsequent <newline> or <control>-J as a literal character, removing any 
special meaning that it may have to the editor during text input mode. The backslash character 
shall be retained and evaluated when the command line is parsed, or retained and included 
when the input text becomes part of the edit buffer. 

<control>-V 

Synopsis: <control>-V 

Allow the entry of any subsequent character as a literal character, removing any special meaning 
that it may have to the editor during text input mode. The <control>-V character shall be 
discarded before the command line is parsed or the input text becomes part of the edit buffer. 

If the "literal next" functionality is performed by the underlying system, it is implementation- 
dependent whether a character other than <control>-V performs this function. 

<control>-W 

Synopsis: <control>-W 

Discard the <control>-W, and the word previous to it in the input line, including any <blank> 
characters following the word and preceding the <control>-W. If the "word erase" functionality 
is performed by the underlying system, it is implementation-dependent whether a character 
other than <control>-W performs this function. 

Command Descriptions in ex 

The following symbols are used in this section to represent command modifiers. Some of these 
modifiers can be omitted, in which case the specified defaults shall be used. 

lnddr A single line address, given in any of the forms described in Addressing in ex on 

page 394; the default shall be the current line (' .'), unless otherwise specified. 

If the line address is zero, it shall be an error, unless otherwise specified in the 
following command descriptions. 

If the edit buffer is empty, and the address is specified with a command other than 
=, append, insert, open, put, read, or visual, or the address is not zero, it shall be 
an error. 

2nddr Two addresses specifying an inclusive range of lines. If no addresses are specified, 

the default for laddr shall be the current line only ("., ."), unless otherwise 
specified in the following command descriptions. If one address is specified, 2addr 
shall specify that line only, unless otherwise specified in the following command 
descriptions. 

It shall be an error if the first address is greater than the second address. 

If the edit buffer is empty, and the two addresses are specified with a command 
other than the !, write, wq, or xit commands, or either address is not zero, it shall 
be an error. 

count A positive decimal number. If count is specified, it shall be equivalent to specifying 

an additional address to the command, unless otherwise specified by the following 
command descriptions. The additional address shall be equal to the last address 
specified to the command (either explicitly or by default) plus count- 1. 
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If this would result in an address greater than the last line of the edit buffer, it shall 
be corrected to equal the last line of the edit buffer. 

flags One or more of the characters ' p', or ' 1' (ell). The flag characters 

can be <blank>-separated, and in any order or combination. The characters ' #', 
' p', and ' 1' shall cause lines to be written in the format specified by the print 
command with the specified flags. 

The lines to be written are as follows: 

1. All edit buffer lines written during the execution of the ex &, list, number, 
open, print, s, visual, and z commands shall be written as specified by flags. 

2. After the completion of an ex command with a flag as an argument, the 
current line shall be written as specified by flags, unless the current line was 
the last line written by the command. 

The characters ' +' and ' cause the value of the current line after the execution 
of the ex command to be adjusted by the offset address as described in Addressing 
in ex on page 394. This adjustment shall occur before the current line is written as 
described in 2. above. 

The default tor flags shall be none. 

buffer One of a number of named areas for holding text. The named buffers are specified 

by the alphanumeric characters of the POSIX locale. There shall also be one 
"unnamed" buffer. When no buffer is specified for editor commands that use a 
buffer, the unnamed buffer shall be used. Commands that store text into buffers 
shall store the text as it was before the command took effect, and shall store text 
occurring earlier in the file before text occurring later in the file, regardless of how 
the text region was specified. Commands that store text into buffers shall store the 
text into the unnamed buffer as well as any specified buffer. 

In ex commands, buffer names are specified as the name by itself. In open or visual 
mode commands the name is preceded by a double quote (' ) ' character. 

If the specified buffer name is an uppercase character, and the buffer contents are 
to be modified, the buffer shall be appended to rather than being overwritten. If 
the buffer is not being modified, specifying the buffer name in lowercase and 
uppercase shall have identical results. 

There shall also be buffers named by the numbers 1 through 9. In open and visual 
mode, if a region of text including characters from more than a single line is being 
modified by the vi c or d commands, the motion character associated with the c or 
d commands specifies that the buffer text shall be in line mode, or the commands 
%,', /, ?, (,), N, n, {, or } are used to define a region of text for the c or d commands, 
the contents of buffers 1 through 8 shall be moved into the buffer named by the 
next numerically greater value, the contents of buffer 9 shall be discarded, and the 
region of text shall be copied into buffer 1. This shall be in addition to copying the 
text into a user-specified buffer or unnamed buffer, or both. Numeric buffers can 
be specified as a source buffer for open and visual mode commands; however, 
specifying a numeric buffer as the write target of an open or visual mode 
command shall have unspecified results. 

The text of each buffer shall have the characteristic of being in either line or 
character mode. Appending text to a non-empty buffer shall set the mode to match 
the characteristic of the text being appended. Appending text to a buffer shall 
cause the creation of at least one additional line in the buffer. All text stored into 
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buffers by ex commands shall be in line mode. The ex commands that use buffers 
as the source of text specify individually how buffers of different modes are 
handled. Each open or visual mode command that uses buffers for any purpose 
specifies individually the mode of the text stored into the buffer and how buffers 
of different modes are handled. 


Command text used to derive a path name. The default shall be the current path 
name, as defined previously, in which case, if no current path name has yet been 
established it shall be an error, except where specifically noted in the individual 
command descriptions that follow. If the command text contains any of the 
characters ' ~,' and ' \', it shall be 
subjected to the process of "shell expansions", as described below; if more than a 
single path name results and the command expects only one, it shall be an error. 


The process of shell expansions in the editor shall be done as follows. The ex utility 
shall pass two arguments to the program named by the shell edit option; the first 
shall be -c, and the second shall be the string "echo" and the command text as a 
single argument. The standard output and standard error of that command shall 
replace the command text. 


A character that can be appended to the command name to modify its operation, 
as detailed in the individual command descriptions. With the exception of the ex 
read, write, and ! commands, the ' !' character shall only act as a modifier if there 
are no <blank> characters between it and the command name. 


remembered search direction 

The vi commands N and n begin searching in a forwards or backwards direction in 
the edit buffer based on a remembered search direction, which is initially unset, 
and is set by the ex global, v, s, and tag commands, and the vi / and ? commands. 


Abbreviate 

Synopsis: ab [breviate] [lhs rhs ] 

If lhs and rhs are not specified, write the current list of abbreviations and do nothing more. 

Implementations may restrict the set of characters accepted in lhs or rh, except that printable 
characters and <blank> characters shall not be restricted. Additional restrictions shall be 
implementation-dependent. 

In both lhs and rhs, any character may be escaped with a <control>-V, in which case the 
character shall not be used to delimit lhs from rhs, and the escaping <control>-V shall be 
discarded. 

In open and visual text input mode, if a non-word or <ESC> character that is not escaped by a 
<control>-V character is entered after a word character, a check shall be made for a set of 
characters matching lhs, in the text input entered during this command. If it is found, the effect 
shall be as if rhs was entered instead of lhs. 

The set of characters that are checked is defined as follows: 

1. If there are no characters inserted before the word and non-word or <ESC> characters that 
triggered the check, the set of characters shall consist of the word character. 

2. If the character inserted before the word and non-word or <ESC> characters that triggered 
the check is a word character, the set of characters shall consist of the characters inserted 
immediately before the triggering characters that are word characters, plus the triggering 
word character. 
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15349 3. If the character inserted before the word and non-word or <ESC> characters that triggered I 

15350 the check is not a word character, the set of characters shall consist of the characters that I 

15351 were inserted before the triggering characters that are neither <blank> characters nor word I 

15352 characters, plus the triggering word character. I 

15353 It is unspecified whether the Iks argument entered for the ex abbreviate and unabbreviate I 

15354 commands is replaced in this fashion. Regardless of whether or not the replacement occurs, the I 

15355 effect of the command shall be as if the replacement had not occurred. I 

15356 Current line: Unchanged. I 

15357 Current column: Unchanged. I 

15358 Append 

15359 Synopsis: [ laddr ] a [ppend] [ ! ] 

15360 Enter text input mode; the input text shall be placed after the specified line. If line zero is I 

15361 specified, the text shall be placed at the beginning of the edit buffer. I 

15362 This command shall be affected by the number and autoindent edit options; following the I 

15363 command name with ' !' shall cause the autoindent edit option setting to be toggled for the I 

15364 duration of this command only. I 

15365 Current line: Set to the last input line; if no lines were input, set to the specified line, or to the I 

15366 first line of the edit buffer if a line of zero was specified, or zero if the edit buffer is empty. I 

15367 Current column: Set to non-<blank>. I 

15368 Arguments 

15369 Synopsis: ar [gs] 

15370 Write the current argument list, with the current argument-list entry, if any, between ' [' and I 

15371 ' ] ' characters. I 

15372 Current line: Unchanged. I 

15373 Current column: Unchanged. I 

15374 Change 

15375 Synopsis: [2addr ] c[hange] [!] [count] 

15376 Enter ex text input mode; the input text shall replace the specified lines. The specified lines shall I 

15377 be copied into the unnamed buffer, which shall become a line mode buffer. I 

15378 This command shall be affected by the number and autoindent edit options; following the I 

15379 command name with ' !' shall cause the autoindent edit option setting to be toggled for the I 

15380 duration of this command only. I 

15381 Current line: Set to the last input line; if no lines were input, set to the line before the first I 

15382 address, or to the first line of the edit buffer if there are no lines preceding the first address, or to I 

15383 zero if the edit buffer is empty. I 

15384 Current column: Set to non-<blank>. I 
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Change Directory 

Synopsis: chd[ir] [!] [ directory] 

cd[!] [directory] 

Change the current working directory to directory . I 

If no directory argument is specified, and the HOME environment variable is set to a non-null I 
and non-empty value, directory shall default to the value named in the HOME environment I 
variable. If the HOME environment variable is empty or is undefined, the default value of I 
directory is implementation-dependent. I 

If no ' !' is appended to the command name, and the edit buffer has been modified since the I 
last complete write, and the current path name does not begin with a ' /', it shall be an error. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Copy 

Synopsis: [ 2addr ] co[py] laddr [flags] 

[2addr] t laddr [flags] 

Copy the specified lines after the specified destination line; line zero specifies that the lines shall I 
be placed at the beginning of the edit buffer. I 

Current line: Set to the last line copied. I 

Current column: Set to non-<blank>. I 

Delete 

Synopsis: [2addr] d[elete] [buffer] [count] [flags] 

Delete the specified lines into a buffer (defaulting to the unnamed buffer), which shall become a I 
line-mode buffer. I 

Flags can immediately follow the command name; see Command Line Parsing in ex on page I 
396. I 

Current line: Set to the line following the deleted lines, or to the last line in the edit buffer if that I 
line is past the end of the edit buffer, or to zero if the edit buffer is empty. I 

Current column: Set to non-<blank>. I 

Edit 

Synopsis: e [dit] [ ! ] [tcommand] [file] I 

ex[!] [+command][file] 

If no ' !' is appended to the command name, and the edit buffer has been modified since the I 
last complete write, it shall be an error. I 

lifile is specified, replace the current contents of the edit buffer with the current contents of file, I 
and set the current path name to file, lifile is not specified, replace the current contents of the I 
edit buffer with the current contents of the file named by the current path name. If for any I 
reason the current contents of the file cannot be accessed, the edit buffer shall be empty. I 

The +command option shall be <blank> character-delimited; <blank> characters within I 
+command can be escaped by preceding them with a backslash character. The +command shall be I 
interpreted as an ex command immediately after the contents of the edit buffer have been I 
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replaced and the current line and column have been set. 

If the edit buffer is empty: 

Current line: Set to 0. 

Current column: Set to 1. 

Otherwise, if executed while in ex command mode or if the +command argument is specified: 
Current line: Set to the last line of the edit buffer. 

Current column: Set to non-<blank>. 

Otherwise, if file is omitted or results in the current path name: 

Current line: Set to the first line of the edit buffer. 

Current column: Set to non-<blank>. 

Otherwise, if file is the same as the last file edited, the line and column shall be set as follows; if 
the file was previously edited, the line and column may be set as follows: 

Current line: Set to the last value held when that file was last edited. If this value is not a valid 
line in the new edit buffer, set to the first line of the edit buffer. 

Current column: If the current line was set to the last value held when the file was last edited, set 
to the last value held when the file was last edited. Otherwise, or if the last value is not a valid 
column in the new edit buffer, set to non-<blank>. 

Otherwise: 

Current line: Set to the first line of the edit buffer. 

Current column: Set to non-<blank>. 

File 

Synopsis: f[ile] [file] 

If a file argument is specified, the alternate path name shall be set to the current path name, and 
the current path name shall be set to file. 

Write an informational message. If the file has a current path name, it shall be included in this 
message; otherwise, the message shall indicate that there is no current path name. If the edit 
buffer contains lines, the current line number and the number of lines in the edit buffer shall be 
included in this message; otherwise, the message shall indicate that the edit buffer is empty. If 
the edit buffer has been modified since the last complete write, this fact shall be included in this 
message. If the readonly edit option is set, this fact shall be included in this message. The 
message may contain other unspecified information. 

Current line: Unchanged. 

Current column: Unchanged. 
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Global 

Synopsis: [ 2addr ] gflobal] /pattern/ [commands ] 

[ 2addr ] v /pattern/ [ commands ] 

The optional ' !' character after the global command shall be the same as executing the v 
command. 

If pattern is empty (for example, " / / ") or not specified, the last regular expression used in the 
editor command shall be used as the pattern. The patterncanbedelimited by slashes (shown in 
the Synopsis), as well as any non-alphanumeric or non-<blank> character other than backslash, 
vertical line, double quote, or <newline>. 

If no lines are specified, the lines shall default to the entire file. 

The global and v commands are logically two-pass operations. First, mark the lines within the 
specified lines that match (global) or do not match (v or global!) the specified pattern. Second, 
execute the ex commands given by commands, with the current line (' .') set to each marked 
line. If an error occurs during this process, or the contents of the edit buffer are replaced (for 
example, by the ex :edit command) an error message shall be written and no more commands 
resulting from the execution of this command shall be processed. 

Multiple ex commands can be specified by entering multiple commands on a single line using a 
vertical line to delimit them, or one per line, by escaping each <newline> with a backslash. 

If no commands are specified: 

1. If in ex command mode, it shall be as if the print command were specified. 

2. Otherwise, no command shall be executed. 

For the append, change, and insert commands, the input text shall be included as part of the 
command, and the terminating period can be omitted if the command ends the list of 
commands. The open and visual commands can be specified as one of the commands, in which 
case each marked line shall cause the editor to enter open or visual mode. If open or visual mode 
is exited using the vi Q command, the current line shall be set to the next marked line, and open 
or visual mode reentered, until the list of marked lines is exhausted. 

The global, v, and undo commands cannot be used in commands. Marked lines may be deleted 
by commands executed for lines occurring earlier in the file than the marked lines. In this case, 
no commands shall be executed for the deleted lines. 

If the remembered search direction is not set, the global and v commands shall set it to forward. 

The autoprint and autoindent edit options shall be inhibited for the duration of the g or v 
command. 

Current line: If no commands executed, set to the last marked line. Otherwise, as specified for 
the executed ex commands. 

Current column: If no commands are executed, set to non-<blank>; otherwise, as specified for the 
individual ex commands. 
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Insert 

Synopsis: [laddr ] i[nsert] [!] 

Enter ex text input mode; the input text shall be placed before the specified line. If the line is zero 
or 1, the text shall be placed at the beginning of the edit buffer. 

This command shall be affected by the number and autoindent edit options; following the 
command name with ' !' shall cause the autoindent edit option setting to be toggled for the 
duration of this command only. 

Current line: Set to the last input line; if no lines were input, set to the line before the specified 
line, or to the first line of the edit buffer if there are no lines preceding the specified line, or zero 
if the edit buffer is empty. 

Current column: Set to non-<blank>. 

Join 

Synopsis: [2addr ] j [oin] [!] [count] [flags] 

If count is specified: 

If no address was specified, the join command shall behave as if laddr were the current line 
and the current line plus count (.,. + count). 

If one address was specified, the join command shall behave as if 2addr were the specified 
address and the specified address plus count ( addr,addr + count). 

If two addresses were specified, the join command shall behave as if an additional address, 
equal to the last address plus count -1 ( addrl ,addrl,addr2 + count -1), was specified. 

If this would result in a second address greater than the last line of the edit buffer, it shall be 
corrected to be equal to the last line of the edit buffer. 

If no count is specified: 

If no address was specified, the join command shall behave as if 2addr were the current line 
and the next line (.,. +1). 

If one address was specified, the join command shall behave as if laddr were the specified 
address and the next line ( addr,addr +1). 

Join the text from the specified lines together into a single line, which shall replace the specified 
lines. 

If a ' !' character is appended to the command name, the join shall be without modification of 
any line, independent of the current locale. 

Otherwise, in the POSIX locale, set the current line to the first of the specified lines, and then, for 
each subsequent line, proceed as follows: 

1. Discard leading <space>s from the line to be joined. 

2. If the line to be joined is now empty, delete it, and skip steps 3. through 5. 

3. If the current line ends in a <blank> character, or the first character of the line to be joined 
is a ' ) ' character, join the lines without further modification. 

4. If the last character of the current line is a ' .', join the lines with two <space> characters 
between them. 
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5. Otherwise, join the lines with a single <space> character between them. 

Current line : Set to the first line specified. 

Current column: Set to non-<blank>. 

List 

Synopsis: [2addr] l[ist] [count] [flags] 

This command shall be equivalent to the ex command: 

[2addr] p[rint] [count] 1 [flags] 

See Print on page 413. 

Map 

Synopsis: map [ ! ] [lhs rhs] 

If lhs and rhs are not specified: 

1. If ' ! ' is specified, write the current list of text input mode maps. 

2. Otherwise, write the current list of command mode maps. 

3. Do nothing more. 

Implementations may restrict the set of characters accepted in lhs or rhs, except that printable 
characters and <blank> characters shall not be restricted. Additional restrictions shall be 
implementation-dependent. In both lhs and rhs, any character can be escaped with a 
<control>-V, in which case the character shall not be used to delimit lhs from rhs, and the 
escaping <control>-V shall be discarded. 

If the character ' !' is appended to the map command name, the mapping shall be effective 
during open or visual text input mode rather than open or visual command mode. This allows 
lhs to have two different map definitions at the same time: one for command mode and one for 
text input mode. 

For command mode mappings: 

When the lhs is entered as any part of a vi command in open or visual mode (but not as part 
of the arguments to the command), the action shall be as if the corresponding rhs had been 
entered. 

If any character in the command, other than the first, is escaped using a <control>-V 
character, that character shall not be part of a match to an lhs. 

It is unspecified whether implementations shall support map commands where the lhs is 
more than a single character in length, where the first character of the lhs is printable. 

If lhs contains more than one character and the first character is ' #', followed by a sequence 
of digits corresponding to a numbered function key, then when this function key is typed it 
shall be mapped to rhs . Characters other than digits following a ' #' character also 
represent the function key named by the characters in the lhs following the ' #' and may be 
mapped to rhs. It is unspecified how function keys are named or what function keys are 
supported. 

For text input mode mappings: 
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When the Iks is entered as any part of text entered in open or visual text input modes, the 
action shall be as if the corresponding rhs had been entered. 

If any character in the input text is escaped using a <control>-V character, that character shall 
not be part of a match to an Iks. 

It is unspecified whether the Iks argument entered for the map or unmap commands is 
replaced in this fashion. Regardless of whether or not the replacement occurs, the effect of 
the command shall be as if the replacement had not occurred. 

If only part of the Iks is entered, it is unspecified how long the editor will wait for additional, 
possibly matching characters before treating the already entered characters as not matching the 
Ihs. 

The rhs characters shall themselves be subject to remapping, unless otherwise specified by the 
remap edit option, except that if the characters in Ihs occur as prefix characters in rhs, those 
characters shall not be remapped. 

On block-mode terminals, the mapping need not occur immediately (for example, it may occur 
after the terminal transmits a group of characters to the system), but it shall achieve the same 
results as if it occurred immediately. 

Current line: Unchanged. 

Current column: Unchanged. 

Mark 

Synopsis: [ laddr ] ma[rk] character 

[laddr ] k character 

Implementations shall support character values of a single lowercase letter of the POSIX locale 
and the characters ' '' and '''; support of other characters is implementation-dependent. 

If executing the vi m command, set the specified mark to the current line and 1-based numbered 
character referenced by the current column, if any; otherwise, column position 1. 

Otherwise, set the specified mark to the specified line and 1-based numbered first non-<blank> 
character in the line, if any; otherwise, the last character in the line, if any; otherwise, column 
position 1. 

The mark shall remain associated with the line until the mark is reset or the line is deleted. If a 
deleted line is restored by a subsequent undo command, any marks previously associated with 
the line, which have not been reset, shall be restored as well. Any use of a mark not associated 
with a current line in the edit buffer shall be an error. 

The marks ‘ and ' shall be set as described previously, immediately before the following events 
occur in the editor: 

1. The use of ' $' as an ex address 

2. The use of a positive decimal number as an ex address 

3. The use of a search command as an ex address 

4. The use of a mark reference as an ex address 

5. The use of the following open and visual mode commands: <control>-], %, (,), [, ], {,}. 

6. The use of the following open and visual mode commands: ', G, H, L, M, z if the current 
line will change as a result of the command 
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7. The use of the open and visual mode commands: /, ?, N,n if the current line or column I 

will change as a result of the command I 

8. The use of the ex mode commands: z, undo, global, v I 

For rules 1., 2., 3., and 4., the ' and ' marks shall not be set if the ex command is parsed as I 
specified by rule 6.a. in Command Line Parsing in ex on page 396. I 

For rules 5., 6., and 7., the ' and ' marks shall not be set if the commands are used as motion I 
commands in open and visual mode. I 

For rules 1., 2., 3., 4., 5., 6., 7., and 8., the' and' marks shall not be set if the command fails. I 

The ' and ' marks shall be set as described previously, each time the contents of the edit buffer I 
are replaced (including the editing of the initial buffer), if in open or visual mode, or if in ex I 
mode and the edit buffer is not empty, before any commands or movements (including I 
commands or movements specified by the -c or -t options or the +command argument) are I 
executed on the edit buffer. If in open or visual mode, the marks shall be set as if executing the vi I 
m command; otherwise, as if executing the ex mark command. I 

When changing from ex mode to open or visual mode, if the ' and ' marks are not already set, I 
the' and ' marks shall be set as described previously. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Move 

Synopsis: [2addr ] m[ove] laddr [flags] 

Move the specified lines after the specified destination line. A destination of line zero specifies I 
that the lines shall be placed at the beginning of the edit buffer. It shall be an error if the I 
destination line is within the range of lines to be moved. I 

Current line: Set to the last of the moved lines. I 

Current column: Set to non-<blank>. I 

Next 

Synopsis: n[ext] [!] [ + command] [file . . .] 

If no ' !' is appended to the command name, and the edit buffer has been modified since the I 
last complete write, it shall be an error, unless the file is successfully written as specified by the I 
autowrite option. I 

If one or more files is specified: I 

1. Set the argument list to the specified file names. I 

2. Set the current argument list reference to be the first entry in the argument list. I 

3. Set the current path name to the first file name specified. I 

Otherwise: I 

1. It shall be an error if there are no more file names in the argument list after the file name I 

currently referenced. I 

2. Set the current path name and the current argument list reference to the file name after the I 

file name currently referenced in the argument list. I 
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Replace the contents of the edit buffer with the contents of the file named by the current path I 
name. If for any reason the contents of the file cannot be accessed, the edit buffer shall be empty. I 

This command shall be affected by the autowrite and writeany edit options. I 

The +command option shall be <blank> character-delimited; <blank> characters can be escaped I 
by preceding them with a backslash character. The +command shall be interpreted as an ex I 
command immediately after the contents of the edit buffer have been replaced and the current I 
line and column have been set. I 

Current line: Set as described for the edit command. I 

Current column: Set as described for the edit command. I 

Number 

Synopsis: [ 2addr ] nu[mber] [count] [flags] 

[2addr] # [count][flags] 

These commands shall be equivalent to the ex command: I 

[2addr] p[rint] [count] #[flags] 

See I 

Open 

Synopsis: [laddr] o[pen] /pattern/ [flags] 

This command need not be supported on block-mode terminals or terminals with insufficient I 
capabilities. If standard input, standard output, or standard error are not terminal devices, the I 
results are unspecified. I 

Enter open mode. I 

The trailing delimiter can be omitted from pattern at the end of the command line. If pattern is I 
empty (for example, " / / ") or not specified, the last regular expression used in the editor shall be I 
used as the pattern. The pattern can be delimited by slashes (shown in the Synopsis), as well as I 
any alphanumeric, or non-<blank> character other than backslash, vertical line, double quote, or I 
<newline> character. I 

Current line: Set to the specified line. I 

Current column: Set to non-<blank>. I 

Preserve 

Synopsis: pre [serve] 

Save the edit buffer in a form that can later be recovered by using the -r option or by using the ex I 
recover command. After the file has been preserved, a mail message shall be sent to the user. I 
This message shall be readable by invoking the mailx utility. The message shall contain the name I 
of the file, the time of preservation, and an ex command that could be used to recover the file. 
Additional information may be included in the mail message. I 

Current line: Unchanged. I 

Current column: Unchanged. I 
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Print 

Synopsis: [ 2addr ] p[rint] [count] [flags] I 

Write the addressed lines. The behavior is unspecified if the number of columns on the display is I 
less than the number of columns required to write any single character in the lines being written. I 

Non-printable characters, except for the <tab> character, shall be written as implementation- I 
dependent multi-character sequences. 

If the # flag is specified or the number edit option is set, each line shall be preceded by its line I 
number in the following format: I 

"%6dAA", <line number> I 

If the 1 flag is specified or the list edit option is set: I 

1. The characters listed in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

Table 5-1, Escape Sequences and Associated Actions shall be written as the corresponding I 
escape sequence. I 

2. Non-printable characters not in the System Interface Definitions volume of I 

IEEE Std. 1003.1-200x, Table 5-1, Escape Sequences and Associated Actions shall be written I 
as one three-digit octal number (with a preceding backslash) for each byte in the character I 

(most significant byte first). If the size of a byte on the system is greater than 9 bits, the I 

format used for non-printable characters is implementation-dependent. I 

3. The end of each line shall be marked with a ' $', and literal ' $' characters within the line I 

shall be written with a preceding backslash. I 

Long lines shall be folded; the length at which folding occurs is unspecified, but should be I 
appropriate for the output terminal, considering the number of columns of the terminal. I 

If a line is folded, and the 1 flag is not specified and the list edit option is not set, it is unspecified I 

whether a multi-column character at the folding position is separated; it shall not be discarded. I 

Current line: Set to the last written line. I 

Current column: Unchanged if the current line is unchanged; otherwise, set to non-<blank>. I 

Put 

Synopsis: [laddr] pu [t] [buffer] 

Append text from the specified buffer (by default, the unnamed buffer) to the specified line; line I 
zero specifies that the text shall be placed at the beginning of the edit buffer. Each portion of a I 
line in the buffer shall become a new line in the edit buffer, regardless of the mode of the buffer. I 

Current line: Set to the last line entered into the edit buffer. I 

Current column: Set to non-<blank>. I 

Quit 

Synopsis: q[uit] [ ! ] 

If no ' !' is appended to the command name: I 

1. If the edit buffer has been modified since the last complete write, it shall be an error. I 

2. If there are file names in the argument list after the file name currently referenced, and the I 

last command was not a quit, wq, xit, or ZZ (see Exit on page 1064) command, it shall be I 
an error. I 
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Otherwise, terminate the editing session. 

Read 

Synopsis: [laddr ] r[ead] [!] [file] 

If ' !' is not the first non-<blank> character to follow the command name, a copy of the 
specified file shall be appended into the edit buffer after the specified line; line zero specifies that 
the copy shall be placed at the beginning of the edit buffer. The number of lines and bytes read 
shall be written. If no file is named, the current path name shall be the default. If there is no 
current path name, then file shall become the current path name. If there is no current path name 
or file operand, it shall be an error. Specifying a file that is not of type regular shall have 
unspecified results. 

Otherwise, it file is preceded by ' !', the rest of the line after the ' !' shall have ' %', ' #', and 
' !' characters expanded as described in Command Line Parsing in ex on page 396. 

The ex utility shall then pass two arguments to the program named by the shell edit option; the 
first shall be -c and the second shall be the expanded arguments to the read command as a 
single argument. The standard input of the program shall be set to the standard input of the ex 
program when it was invoked. The standard error and standard output of the program shall be 
appended into the edit buffer after the specified line. 

Each line in the copied file or program output (as delimited by <newline> characters or the end 
of the file or output if it is not immediately preceded by a <newline> character), shall be a 
separate line in the edit buffer. Any occurrences of <carriage-return> and <newline> character 
pairs in the output shall be treated as single <newline> characters. 

The special meaning of the ' !' following the read command can be overridden by escaping it 
with a backslash character. 

Current line: If no lines are added to the edit buffer, unchanged. Otherwise, if in open or visual 
mode, set to the first line entered into the edit buffer. Otherwise, set to the last line entered into 
the edit buffer. 

Current column: Set to non-<blank>. 

Recover 

Synopsis: rec[over] [!] file 

If no ' !' is appended to the command name, and the edit buffer has been modified since the 
last complete write, it shall be an error. 

If no file operand is specified, then the current path name shall be used. If there is no current 
path name or file operand, it shall be an error. 

If no recovery information has previously been saved about file, the recover command shall 
behave identically to the edit command, and an informational message to this effect shall be 
written. 

Otherwise, set the current path name to file, and replace the current contents of the edit buffer 
with the recovered contents otfile. If there are multiple instances of the file to be recovered, the 
one most recently saved shall be recovered, and an informational message that there are 
previous versions of the file that can be recovered shall be written. The editor shall behave as if 
the contents of the edit buffer have already been modified. 

Current file: Set as described for the edit command. 
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Current column: Set as described for the edit command. I 

Rewind 

Synopsis: rew[ind][!] 

If no ' !' is appended to the command name, and the edit buffer has been modified since the I 
last complete write, it shall be an error, unless the file is successfully written as specified by the I 
autowrite option. I 

If the argument list is empty, it shall be an error. I 

The current argument list reference and the current path name shall be set to the first file name I 
in the argument list. I 

Replace the contents of the edit buffer with the contents of the file named by the current path I 
name. If for any reason the contents of the file cannot be accessed, the edit buffer shall be empty. I 

This command shall be affected by the autowrite and writeany edit options. I 

Current line: Set as described for the edit command. I 

Current column: Set as described for the edit command. I 

Set 

Synopsis: se [t] [option [= [value] ] . . . ] [no option ...] [option? ...][all] 

When no arguments are specified, write the value of the term edit option and those options I 
whose values have been changed from the default settings; when the argument all is specified, I 
write all of the option values. 

Giving an option name followed by the character ' ?' shall cause the current value of that 
option to be written. The ' ?' can be separated from the option name by zero or more <blank> 
characters. The ' ?' shall be necessary only for Boolean valued options. Boolean options can be I 
given values by the form set option to turn them on or set nooption to turn them off; string and I 
numeric options can be assigned by the form set option -value. Any <blank> characters in strings I 
can be included as is by preceding each <blank> with an escaping backslash. More than one I 
option can be set or listed by a single set command by specifying multiple arguments, each I 
separated from the next by one or more <blank> characters. I 

See Edit Options in ex on page 425 for details about specific options. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Shell 

Synopsis: sh[ell] 

Invoke the program named in the shell edit option with the single argument -i (interactive I 
mode). Editing shall be resumed when the program exits. I 

Current line: Unchanged. I 

Current column: Unchanged. I 
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Source 

Synopsis: so[urce] file 

Read and execute ex commands from file. Lines in the file that contain no characters or only I 
<blank> characters shall be ignored. I 

Current line: As specified for the individual ex commands. I 

Current column: As specified for the individual ex commands. I 

Substitute 

Synopsis: [2addr] substitute] [/pattern/repl/ [options] [count] [blags]] 

[2addr] &[ options][count] [blags]] 

[2addr] ~[options][count] [blags]] 

Replace the first instance of the pattern pattern by the string repl on each specified line. (See 
Regular Expressions in ex on page 424 and Replacement Strings in ex on page 425.) Any non- I 
alphabetic, non-<blank> delimiter other than ' \, ' | ', double quote, or <newline> character I 
can be used instead of ' /'. Backslash characters can be used to escape delimiters, backslash I 
characters, and other special characters. I 

The trailing delimiter can be omitted from pattern or from repl at the end of the command line. If I 

both pattern and repl are not specified or are empty (for example, "//"), the last s command I 

shall be repeated. If only pattern is not specified or is empty, the last regular expression used in I 
the editor shall be used as the pattern. If only repl is not specified or is empty, the pattern shall be I 
replaced by nothing. If the entire replacement pattern is ' %', the last replacement pattern to an I 
s command shall be used. I 

Entering a <carriage-return> in repl (which requires an escaping backslash in ex mode and an I 
escaping <control>-V in open or vi mode) shall split the line at that point, creating a new line in I 
the edit buffer. The <carriage-return> shall be discarded. I 

If options include the letter ' g' (global), all non-overlapping instances of the pattern in the line I 
shall be replaced. I 

If options includes the letter ' c' (confirm), then before each substitution the line shall be I 

written; the written line shall reflect all previous substitutions. On the following line, <space> I 

characters shall be written beneath the characters from the line that are before the pattern to be I 

replaced, and ' '' characters written beneath the characters included in the pattern to be I 

replaced. The ex utility shall then wait for a response from the user. An affirmative response I 

shall cause the substitution to be done, while any other input shall not make the substitution. An I 

affirmative response shall consist of a line with the affirmative response (as defined by the I 

current locale) at the beginning of the line. This line shall be subject to editing in the same way as I 
the ex command line. I 

If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications confirmed by the I 
user shall be preserved in the edit buffer after the interrupt. I 

If the remembered search direction is not set, the s command shall set it to forward. I 

In the second Synopsis, the & command shall repeat the previous substitution, as if the & I 
command were replaced by: I 

s /pattern/repl/ I 

where pattern and repl are as specified in the previous s, &, or ~ command. I 
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In the third Synopsis, the ~ command shall repeat the previous substitution, as if the ' ~' were 
replaced by: 

s/ pattern/repl/ 

where pattern shall be the last regular expression specified to the editor, and repl shall be from 
the previous substitution (including & and ~) command. 

These commands shall be affected by the LC_MESSAGES environment variable. 

Current line: Set to the last line in which a substitution occurred, or, unchanged if no 
substitution occurred. 

Current column: Set to non-<blank>. 

Suspend 

Synopsis: su [spend] [! ] 

st[op] [ ! ] 

Allow control to return to the invoking process; ex shall suspend itself as if it had received the 
SIGTSTP signal. The suspension shall occur only if job control is enabled in the invoking shell 
(see the description of set -m). 

These commands shall be affected by the autowrite and writeany edit options. 

The current susp character (see stty) shall have the same affect as the suspend command. 

Tag 

Synopsis: ta[g][!] tagstring 

The results are unspecified if the format of a tags file is not as specified by the ctags utility (see 
ctags ) description. 

The tag command shall search for tagstring in the tag files referred to by the tag edit option, in 
the order they are specified, until a reference to tagstring is found. Files shall be searched from 
beginning to end. If no reference is found, it shall be an error and an error message to this effect 
shall be written. If the reference is not found, or if an error occurs while processing a file referred 
to in the tag edit option, it shall be an error, and an error message shall be written at the first 
occurrence of such an error. 

Otherwise, if the tags file contained a pattern, the pattern shall be treated as a regular expression 
used in the editor; for example, for the purposes of the s command. 

If the tagstring is in a file with a different name than the current path name, set the current path 
name to the name of that file, and replace the contents of the edit buffer with the contents of that 
file. In this case, if no ' !' is appended to the command name, and the edit buffer has been 
modified since the last complete write, it shall be an error, unless the file is successfully written 
as specified by the autowrite option. 

This command shall be affected by the autowrite, tag, taglength, and writeany edit options. 

Current line: If the tags file contained a line number, set to that line number. If the line number is 
larger than the last line in the edit buffer, an error message shall be written and the current line 
shall be set as specified for the edit command. 

If the tags file contained a pattern, set to the first occurrence of the pattern in the file. If no 
matching pattern is found, an error message shall be written and the current line shall be set as 
specified for the edit command. 
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Current column: If the tags file contained a line-number reference and that line-number was not I 
larger than the last line in the edit buffer, or if the tags file contained a pattern and that pattern I 
was found, set to non-<blank>. Otherwise, set as specified for the edit command. I 

Unabbreviate 

Synopsis: una[bbrev] lhs 

If lhs is not an entry in the current list of abbreviations (see Abbreviate on page 403), it shall be I 
an error. Otherwise, delete lhs from the list of abbreviations. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Undo 

Synopsis: u[ndo] 

Reverse the changes made by the last command that modified the contents of the edit buffer, I 
including undo. For this purpose, the global, v, open, and visual commands, and commands I 
resulting from buffer executions and mapped character expansions, are considered single I 
commands. I 

If no action that can be undone preceded the undo command, it shall be an error. I 

If the undo command restores lines that were marked, the mark shall also be restored unless it I 

was reset subsequent to the deletion of the lines. I 

Current line: I 

1. If lines are added or changed in the file, set to the first line added or changed. I 

2. Set to the line before the first line deleted, if it exists. I 

3. Set to 1 if the edit buffer is not empty. I 

4. Set to zero. I 

Current column: Set to non-<blank>. I 

Unmap 

Synopsis: unm[ap] [! ] lhs 

If ' !' is appended to the command name, and if lhs is not an entry in the list of text input mode I 
map definitions, it shall be an error. Otherwise, delete lhs from the list of text input mode map I 
definitions. I 

If no ' ! ' is appended to the command name, and if lhs is not an entry in the list of command I 
mode map definitions, it shall be an error. Otherwise, delete lhs from the list of command mode I 
map definitions. I 

Current line: Unchanged. I 

Current column: Unchanged. I 
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Version I 

Synopsis: ve[rsion] I 

Write a message containing version information for the editor. The format of the message is I 
unspecified. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Visual 

Synopsis: [laddr ] vi[sual] [type] [count] [flags] 

If ex is currently in open or visual mode, the Synopsis and behavior of the visual command shall I 
be the same as the edit command, as specified by Edit on page 405. I 

Otherwise, this command need not be supported on block-mode terminals or terminals with I 
insufficient capabilities. If standard input, standard output, or standard error are not terminal I 
devices, the results are unspecified. I 

If count is specified, the value of the window edit option shall be set to count (as described in I 
window on page 432). If the ' "' type character was also specified, the window edit option shall I 
be set before being used by the type character. I 

Enter visual mode. If type is not specified, it shall be as if a type of ' + ' was specified. The type I 
shall cause the following effects: I 

+ Place the beginning of the specified line at the top of the display. I 

Place the end of the specified line at the bottom of the display. I 

Place the beginning of the specified line in the middle of the display. I 

A If the specified line is less than or equal to the value of the window edit option, set the line I 
to 1; otherwise, decrement the line by the value of the window edit option minus 1. Place I 
the beginning of this line as close to the bottom of the displayed lines as possible, while still I 
displaying the value of the window edit option number of lines. I 

Current line: Set to the specified line. I 

Current column: Set to non-<blank>. I 

Write 

Synopsis: [ 2addr ] w[rite] [!] [>>] [file] I 

[2addr] w[rite][!] [file] 

[2addr] wq[!][>>][Tile] 

If no lines are specified, the lines shall default to the entire file. I 

The command wq shall be equivalent to a write command followed by a quit command; wq! I 
shall be equivalent to write! followed by quit. In both cases, if the write command fails, the I 
quit shall not be attempted. I 

If the command name is not followed by one or more <blank> characters, or file is not preceded I 
by a ' !' character, the write shall be to a file. I 

1. If the » argument is specified, and the file already exists, the lines shall be appended to I 
the file instead of replacing its contents. If the » argument is specified, and the file does I 
not already exist, it is unspecified whether the write shall proceed as if the » argument I 
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had not been specified or if the write shall fail. 

2. If the readonly edit option is set (see readonly on page 429), the write shall fail. 

3. lifile is specified, and is not the current path name, and the file exists, the write shall fail. 

4. If/z7e is not specified, the current path name shall be used. If there is no current path name, 
the write command shall fail. 

5. If the current path name is used, and the current path name has been changed by the file 
or read commands, and the file exists, the write shall fail. If the write is successful, 
subsequent writes shall not fail for this reason (unless the current path name is changed 
again). 

6. If the whole edit buffer is not being written, and the file to be written exists, the write shall 
fail. 

For rules 1., 2., 4., and 5., the write can be forced by appending the character ' !' to the 
command name. 

For rules 2., 4., and 5., the write can be forced by setting the writeany edit option. 

Additional, implementation-dependent tests may cause the write to fail. 

If the edit buffer is empty, a file without any contents shall be written. 

An informational message shall be written noting the number of lines and bytes written. 

Otherwise, if the command is followed by one or more <blank> characters, and file is preceded 
by ' !', the rest of the line after the ' !' shall have ' %', ' #', and ' !' characters expanded as 
described in Command Line Parsing in ex on page 396. 

The ex utility shall then pass two arguments to the program named by the shell edit option; the 
first shall be -c and the second shall be the expanded arguments to the write command as a 
single argument. The specified lines shall be written to the standard input of the command. The 
standard error and standard output of the program, if any, shall be written as described for the 
print command. If the last character in that output is not a <newline> character, a <newline> 
shall be written at the end of the output. 

The special meaning of the ' !' following the write command can be overridden by escaping it 
with a backslash character. 

Current line: Unchanged. 

Current column: Unchanged. 

Write and Exit 

Synopsis: [ 2addr ] x [it] [!] [file] 

If the edit buffer has not been modified since the last complete write, xit shall be equivalent to 
the quit command, or if a ' !' is appended to the command name, to quit!. 

Otherwise, xit shall be equivalent to the wq command, or if a ' !' is appended to the command 
name, to wq!. 

Current line: Unchanged. 

Current line: Unchanged. 
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Yank 

Synopsis: [ 2addr ] ya[nk] [ buffer] [count] 

Copy the specified lines to the specified buffer (by default, the unnamed buffer), which shall I 
become a line-mode buffer. I 

Current line: Unchanged. I 

Current line: Unchanged. I 

Adjust Window 

Synopsis: [laddr] z [ ! ] [ type . . . ] [count] [flags] 

If no line is specified, the current line shall be the default; if type is omitted as well, the current I 
line value shall first be incremented by 1. If incrementing the current line would cause it to be I 
greater than the last line in the edit buffer, it shall be an error. I 

If there are <blank> characters between the type argument and the preceding z command name I 
or optional ' ! ' character, it shall be an error. I 

If count is specified, the value of the window edit option shall be set to count (as described in I 
window on page 432). If count is omitted, it shall default to 2 times the value of the scroll edit I 

option, or if ! was specified, the number of lines in the display minus 1. I 

If type is omitted, then count lines starting with the specified line shall be written. Otherwise, I 
count lines starting with the line specified by the type argument shall be written. I 

The type argument shall change the lines to be written. The possible values of type are as follows: I 

- The specified line shall be decremented by the following value: I 

(((number of ' '' characters) W count) —1) I 

If the calculation would result in a number less than 1, it shall be an error. Write lines from I 
the edit buffer, starting at the new value of line, until count lines or the last line in the edit I 
buffer has been written. I 

+ The specified line shall be incremented by the following value: I 

(((number of ' ' + '' characters) —1) W count) +1 I 

If the calculation would result in a number greater than the last line in the edit buffer, it I 
shall be an error. Write lines from the edit buffer, starting at the new value of line, until I 
count lines or the last line in the edit buffer has been written. I 

=,. If more than a single ' .' or ' =' is specified, it shall be an error. The following steps shall be I 

taken: I 

1. If count is zero, nothing shall be written. I 

2. Write as many of the N lines before the current line in the edit buffer as exist. If count I 

or ' !' was specified, N shall be: I 

(count -1) /2 I 

Otherwise, N shall be: I 

(count —3) /2 I 

If N is a number less than 3, no lines shall be written. I 
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3. If ' =' was specified as the type character, write a line consisting of the smaller of the 
number of columns in the display divided by two, or 40 ' - ' characters. 

4. Write the current line. 

5. Repeat step 3. 

6. Write as many of the N lines after the current line in the edit buffer as exist. N shall be 
defined as in step 2. If N is a number less than 3, no lines shall be written, current line 
in the edit buffer as exist. If count is less than 3, no lines shall be written. 

A The specified line shall be decremented by the following value: 

(((number of ' '~ '' characters) +1) W count) —1 

If the calculation would result in a number less than 1, it shall be an error. Write lines from 
the edit buffer, starting at the new value of line, until count lines or the last line in the edit 
buffer has been written. 

Current line: Set to the last line written, unless the type is =, in which case, set to the specified 
line. 

Current column: Set to non-<blank>. 

Escape 

Synopsis: ! command 

[nddr] ! command 

The contents of the line after the ' !' shall have ' %', ' #', and ' !' characters expanded as 
described in Command Line Parsing in ex on page 396. If the expansion causes the text of the 
line to change, it shall be redisplayed, preceded by a single ' !' character. 

The ex utility shall execute the program named by the shell edit option. It shall pass two 
arguments to the program; the first shall be -c, and the second shall be the expanded arguments 
to the ! command as a single argument. 

If no lines are specified, the standard input, standard output, and standard error of the program 
shall be set to the standard input, standard output, and standard error of the ex program when it 
was invoked. In addition, a warning message shall be written if the edit buffer has been 
modified since the last complete write, and the warn edit option is set. 

If lines are specified, they shall be passed to the program as standard input, and the standard 
output and standard error of the program shall replace those lines in the edit buffer. Each line in 
the program output (as delimited by <newline> characters or the end of the output if it is not 
immediately preceded by a <newline> character), shall be a separate line in the edit buffer. Any 
occurrences of <carriage-return> and <newline> character pairs in the output shall be treated as 
single <newline> characters. The specified lines shall be copied into the unnamed buffer before 
they are replaced, and the unnamed buffer shall become a line-mode buffer. 

If in ex mode, a single ' !' character shall be written when the program completes. 

This command shall be affected by the shell and warn edit options. If no lines are specified, this 
command shall be affected by the autowrite and writeany edit options. If lines are specified, this 
command shall be affected by the autoprint edit option. 

Current line: 

1. If no lines are specified, unchanged. 
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2. Otherwise, set to the last line read in, if any lines are read in. 

3. Otherwise, set to the line before the first line of the lines specified, if that line exists. 

4. Otherwise, set to the first line of the edit buffer if the edit buffer is not empty. 

5. Otherwise, set to zero. 

Current column: If no lines are specified, unchanged. Otherwise, set to non-<blank>. 

Shift Left 

Synopsis: [ 2addr ] <[< . . .] [count] [flags] 

Shift the specified lines to the start of the line; the number of column positions to be shifted shall 
be the number of command characters times the value of the shiftwidth edit option. Only 
leading <blank> characters shall be deleted or changed into other <blank> characters in shifting; 
other characters shall not be affected. 

Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode 
buffer. 

This command shall be affected by the autoprint edit option. 

Current line: Set to the last line in the lines specified. 

Current column: Set to non-<blank>. 

Shift Right 

Synopsis: [2addr] >[> . . .] [count] [flags] 

Shift the specified lines away from the start of the line; the number of column positions to be 
shifted shall be the number of command characters times the value of the shiftwidth edit option. 
The shift shall be accomplished by adding <blank> characters as a prefix to the line or changing 
leading <blank> characters into other <blank> characters. Empty lines shall not be changed. 

Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode 
buffer. 

This command shall be affected by the autoprint edit option. 

Current line: Set to the last line in the lines specified. 

Current column: Set to non-<blank>. 

<control>-D 

Synopsis: <control>-D 

Write the next n lines, where n is the minimum of the values of the scroll edit option and the 
number of lines after the current line in the edit buffer. If the current line is the last line of the 
edit buffer it shall be an error. 

Current line: Set to the last line written. 

Current column: Set to non-<blank>. 
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Write Line Number 

Synopsis: [laddr ] = [flags] 

If line is not specified, it shall default to the last line in the edit buffer. Write the line number of I 
the specified line. I 

Current line: Unchanged. I 

Current column: Unchanged. I 

Execute 

Synopsis: [2addr] @ buffer 

[2addr] * buffer 

If no buffer is specified or is specified as ' @' or ' *', the last buffer executed shall be used. If no I 
previous buffer has been executed, it shall be an error. I 

For each line specified by the addresses, set the current line (' .') to the specified line, and I 
execute the contents of the named buffer (as they were at the time the @ command was executed) I 
as ex commands. For each line of a line-mode buffer, and all but the last line of a character-mode I 
buffer, the ex command parser shall behave as if the line was terminated by a <newline> I 
character. I 

If an error occurs during this process, or a line specified by the addresses does not exist when the I 
current line would be set to it, or more than a single line was specified by the addresses, and the I 
contents of the edit buffer are replaced (for example, by the ex :edit command) an error message I 
shall be written, and no more commands resulting from the execution of this command shall be I 
processed. I 

Current line: As specified for the individual ex commands. I 

Current column: As specified for the individual ex commands. I 

Regular Expressions in ex 

The ex utility shall support regular expressions that are a superset of the basic regular I 
expressions described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 9.3, Basic Regular Expressions. A null regular expression ("//") shall be equivalent to I 
the last regular expression encountered. I 

Regular expressions can be used in addresses to specify lines and, in some commands (for 
example, the substitute command), to specify portions of a line to be substituted. 

The following constructs can be used to enhance the basic regular expressions: I 

\< Match the beginning of a zvord. (See the definition of zvord at the beginning of Command I 
Descriptions in ex on page 401.) 

\ > Match the end of a zvord. 

Match the replacement part of the last substitute command. The tilde (' ~') character can 
be escaped in a regular expression to become a normal character with no special meaning. I 
The backslash shall be discarded. I 

When the editor option magic is not set, the only characters with special meanings shall be ' ~' I 
at the beginning of a pattern, ' $' at the end of a pattern, and ' \'. The characters ' .', ' *', 

' [', and ' ~' shall be treated as ordinary characters unless preceded by a ' \; when preceded 
by a ' \' they shall regain their special meaning, or in the case of backslash, be handled as a I 
single backslash. Backslashes used to escape other characters shall be discarded. I 
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Replacement Strings in ex 

The character ' &' (' \ &' if the editor option magic is not set) in the replacement string shall I 
stand for the text matched by the pattern to be replaced. The character ' ~' \ ~' if magic is not I 

set) shall be replaced by the replacement part of the previous substitute command. The I 
sequence ' \n', where n is an integer, shall be replaced by the text matched by the pattern I 
enclosed in the nth set of parentheses ' \ (' and ' \ ). I 

The strings ' \1', ' \u', ' \L', and ' \U' can be used to modify the case of elements in the I 
replacement string (using the ' \ &' or "\ "digit) notation. The string ' \1' (' \u') shall cause I 
the character that follows to be converted to lowercase (uppercase). The string ' \L' (' \U') I 
shall cause all characters subsequent to it to be converted to lowercase (uppercase) as they are I 
inserted by the substitution until the string ' \e' or ' \E' , or the end of the replacement string, I 
is encountered. 

Otherwise, any character following a backslash shall be treated as that literal character, and the I 
escaping backslash shall be discarded. I 

An example of case conversion with the s command is as follows: I 

= P 

The cat sat on the mat. 

:s/\<.at\>/\u&/gp 

The Cat Sat on the Mat. 

:s/S\(.*\)M/S\U\l\eM/p 

The Cat SAT ON THE Mat. 

Edit Options in ex I 

The ex utility has a number of options that modify its behavior. These options have default I 
settings, which can be changed using the set command. I 

Options are Boolean unless otherwise specified. 

autoindent, ai 

[Default unset ] I 

If autoindent is set, each line in input mode shall be indented (using first as many <tab> 
characters as possible, as determined by the editor option tabstop, and then using <space> I 
characters) to align with another line, as follows: I 

1. If in open or visual mode and the text input is part of a line-oriented command (see the I 

EXTENDED DESCRIPTION in vi), align to the first column. Otherwise, if in open or I 
visual mode, indentation for each line shall be set as follows: I 

a. If a line was previously inserted as part of this command, it shall be set to the I 

indentation of the last inserted line by default, or as otherwise specified for the I 
<control> character in <REFERENCE UNDEFINED>(vinputctld). I 

b. Otherwise, it shall be set to the indentation of the previous current line, if any; I 

otherwise, to the first column. I 

2. For the ex a, i, and c commands, indentation for each line shall be set as follows: I 

a. If a line was previously inserted as part of this command, it shall be set to the I 
indentation of the last inserted line by default, or as otherwise specified for the eof I 
character in Scroll on page 400. I 
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b. Otherwise, if the command is the ex a command, it shall be set to the line appended 
after, if any; otherwise to the first column. 

c. Otherwise, if the command is the ex i command, it shall be set to the line inserted 
before, if any; otherwise to the first column. 

d. Otherwise, if the command is the ex c command, it shall be set to the indentation of 
the line replaced. 

autoprint, ap 

[Default set] 

If autoprint is set, the current line shall be written after each ex command that modifies the 
contents of the current edit buffer, and after each tag command for which the tag search pattern 
was found or tag line number was valid, unless: 

1. The command was executed while in open or visual mode. 

2. The command was executed as part of a global or v command or @ buffer execution. 

3. The command was the form of the read command that reads a file into the edit buffer. 

4. The command was the append, change, or insert command. 

5. The command was not terminated by a <newline> character. 

6. The current line shall be written by a flag specified to the command; for example, delete # 
shall write the current line as specified for the flag modifier to the delete command, and 
not as specified by the autoprint edit option. 

autowrite, aw 

[Default unset] 

If autowrite is set, and the edit buffer has been modified since it was last completely written to 
any file, the contents of the edit buffer shall be written as if the ex write command had been 
specified without arguments, before each command affected by the autowrite edit option is 
executed. Appending the character ' !' to the command name of any of the ex commands 
except ' !' shall prevent the write. If the write fails, it shall be an error and the command shall 
not be executed. 

beautify, bf 

xsi [Default unset] 

If beautify is set, all non-printable characters, other than <tab>, <newline>, and <form-feed> 
characters, shall be discarded from text read in from files. 

directory, dir 

man [Default implementation-dependent] 

The value of this option specifies the directory in which the editor buffer is to be placed. If this 
directory is not writable by the user, the editor shall quit. 
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16234 edcompatible, ed 

16235 man [Default unset] I 

16236 Causes the presence of g and c suffixes on substitute commands to be remembered, and toggled 

16237 by repeating the suffixes. 

16238 errorbells, eb 

16239 [Default unset] I 

16240 If the editor is in ex mode, and the terminal does not support a standout mode (such as inverse I 

16241 video), and errorbells is set, error messages shall be preceded by alerting the terminal. I 

16242 exrc 

16243 [Default unset] I 

16244 If exrc is set, ex shall access any .exrc file in the current directory, as described in Initialization in I 

16245 ex and vi on page 392. If exrc is not set, ex shall ignore any .exrc file in the current directory I 

16246 during initialization, unless the current directory is that named by the HOME environment I 

16247 variable. I 

16248 ignorecase, ic 

16249 [Default unset] I 

16250 If ignorecase is set, characters that have uppercase and lowercase representations shall have 

16251 those representations considered as equivalent for purposes of regular expression comparison. I 

16252 The ignorecase edit option shall affect all remembered regular expressions; for example, I 

16253 unsetting the ignorecase edit option shall cause a subsequent vi n command to search for the I 

16254 last basic regular expression in a case-sensitive fashion. I 

16255 lisp 

16256 man [Default unset] I 

16257 autoindent mode and the (,), {,}, [[, and ]] commands in visual mode are suitably modified for I 

16258 lisp code. I 

16259 list 

16260 [Default unset] I 

16261 If list is set, edit buffer lines written while in ex command mode shall be written as specified for I 

16262 the print command with the 1 flag specified. In open or visual mode, each edit buffer line shall I 

16263 be displayed as specified for the ex print command with the 1 flag specified. In open or visual I 

16264 text input mode, when the cursor does not rest on any character in the line, it shall rest on the I 

16265 ' $' marking the end of the line. I 
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16266 magic 

16267 [Default set] I 

16268 If magic is set, modify the interpretation of characters in regular expressions and substitution I 

16269 replacement strings (see Regular Expressions in ex on page 424 and Replacement Strings in ex 

16270 on page 425). 

16271 mesg 

16272 [Default set] I 

16273 If mesg is set, the permission for others to use the write or talk commands to write to the I 

16274 terminal shall be turned on while in open or visual mode. The shell-level command mesg n shall I 

16275 take precedence over any setting of the ex mesg option; that is, if mesg y was issued before the I 

16276 editor started (or in a shell escape), such as: I 

16277 : !mesg y 

16278 the mesg option in ex shall suppress incoming messages, but the mesg option shall not enable I 

16279 incoming messages if mesg n was issued. I 

16280 number, nu 

16281 [Default unset] I 

16282 If number is set, edit buffer lines written while in ex command mode shall be written with line I 

16283 numbers, in the format specified by the print command with the # flag specified. In ex text input I 

16284 mode, each line shall be preceded by the line number it will have in the file. I 

16285 In open or visual mode, each edit buffer line shall be displayed with a preceding line number, in I 

16286 the format specified by the ex print command with the # flag specified. This line number shall I 

16287 not be considered part of the line for the purposes of evaluating the current column; that is, I 

16288 column position 1 shall be the first column position after the format specified by the print I 

16289 command. 

16290 paragraphs, para 

16291 [Default in the POSIX locale IPLPPPQPP Llpplpipbp] I 

16292 The paragraphs edit option shall define additional paragraph boundaries for the open and visual I 

16293 mode commands. The paragraphs edit option can be set to a character string consisting of zero I 

16294 or more character pairs. It shall be an error to set it to an odd number of characters. I 

16295 prompt 

16296 [Default set] I 

16297 If prompt is set, ex command mode input shall be prompted for with a colon (' :'); when unset, I 

16298 no prompt shall be written. 
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readonly 

[Default see text] I 

If readonly edit option is set, read-only mode shall be enabled (see Write on page 419). The I 
readonly edit option shall be initialized to set if either of the following conditions are true: I 

• The command-line option -R was specified. I 

• Performing actions equivalent to the access () function called with the following arguments I 

indicates that the file lacks write permission: I 

1. The current path name is used as the path argument. I 

2. The constant W_OK is used as the amode argument. I 

The readonly edit option may be initialized to set for other, implementation-dependent reasons. I 
The readonly edit option shall not be initialized to unset based on any special privileges of the I 
user or process. The readonly edit option shall be reinitialized each time that the contents of the I 
edit buffer are replaced (for example, by an edit or next command) unless the user has explicitly I 
set it, in which case it shall remain set until the user explicitly unsets it. Once unset, it shall again I 
be reinitialized each time that the contents of the edit buffer are replaced. I 

redraw 

[Default unset] I 

The editor simulates an intelligent terminal on a dumb terminal. (Since this is likely to require a 
large amount of output to the terminal, it is useful only at high transmission speeds.) 

remap 

[Default set] I 

If remap is set, map translation shall allow for maps defined in terms of other maps; translation I 
shall continue until a final product is obtained. If unset, only a one-step translation shall be done. I 

report 

[Default 5] 

The value of this report edit option specifies what number of lines being added, copied, deleted, I 
or modified in the edit buffer will cause an informational message to be written to the user. The I 
following conditions shall cause an informational message. The message shall contain the I 
number of lines added, copied, deleted, or modified, but is otherwise unspecified. I 

• An ex or vi editor command, other than open, undo, or visual, that modifies at least the value I 
of the report edit option number of lines, and which is not part of an ex global or v I 
command, or ex or vi buffer execution, shall cause an informational message to be written. I 

• An ex yank or vi y or Y command, that copies at least the value of the report edit option plus I 

1 number of lines, and which is not part of an ex global or v command, or ex or vi buffer I 
execution, shall cause an informational message to be written. I 

• An ex global, v, open, undo, or visual command or ex or vi buffer execution, that adds or I 

deletes a total of at least the value of the report edit option number of lines, and which is not I 
part of an ex global or v command, or ex or vi buffer execution, shall cause an informational I 
message to be written. (For example, if 3 lines were added and 8 lines deleted during an ex I 
visual command, 5 would be the number compared against the report edit option after the I 
command completed. I 
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16340 scroll, scr I 

16341 [Default (number of lines in the display —1)/2] I 

16342 The value of the scroll edit option shall determine the number of lines scrolled by by the ex I 

16343 <control>-D and z commands. For the vi <control>-D and <control>-U commands, it shall be the I 

16344 initial number of lines to scroll when no previous <control>-D or <control>-U command has I 

16345 been executed. I 

16346 sections 

16347 [Default in the POSIX locale NHSHH HUnhsh] I 

16348 The sections edit option shall define additional section boundaries for the open and visual mode I 

16349 commands. The sections edit option can be set to a character string consisting of zero or more I 

16350 character pairs; it shall be an error to set it to an odd number of characters. I 

16351 shell, sh 

16352 [Default from the environment variable SHELL] I 

16353 The value of this option shall be a string. The default shall be taken from the SHELL I 

16354 environment variable. If the SHELL environment variable is null or empty, the sh (see sh) utility I 

16355 shall be the default. I 

16356 shiftwidth, sw 

16357 [Default 8] 

16358 The value of this option shall give the width in columns of an indentation level used during I 

16359 autoindentation and by the shift commands (< and >). I 

16360 showmatch, sm 

16361 [Default unset] I 

16362 The functionality described for the showmatch edit option need not be supported on block- I 

16363 mode terminals or terminals with insufficient capabilities. I 

16364 If showmatch is set, in open or visual mode, when a ' ) ' or ' }' is typed, if the matching ' (' or I 

16365 ' {' is currently visible on the display, the matching ' (' or ' {' shall be flagged moving the I 

16366 cursor to its location for an unspecified amount of time. I 

16367 showmode 

16368 [Default unset] I 

16369 If showmode is set, in open or visual mode, the current mode that the editor is in shall be I 

16370 displayed on the last line of the display. Command mode and text input mode shall be I 

16371 differentiated; other unspecified modes and implementation-dependent information may be I 

16372 displayed. I 
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slowopen I 

[Default unset ] I 

If slowopen is set during open and visual text input modes, the editor shall not update portions I 
of the display other than those screen columns that display the characters entered by the user I 
(see Input Mode Commands in vi on page 1064). I 

tabstop, ts 
[Default 8] 

The value of this edit option shall specify the column boundary used by a <tab> character in the I 
display (see autoprint, ap on page 426 and Input Mode Commands in vi on page 1064). I 

taglength, tl I 

[Default zero] I 

The value of this edit option shall specify the maximum number of characters that are I 
considered significant in the user-specified tag name and in the tag name from the tags file. If the I 
value is zero, all characters in both tag names shall be significant. I 

tags 

[Default see text] 

The value of this edit option shall be a string of <blank> character-delimited path names of files I 
used by the tag command. The default value is unspecified. I 

term 

[Default from the environment variable TERM] I 

The value of this edit option shall be a string. The default shall be taken from the TERM variable I 
in the environment. If the TERM environment variable is empty or null, the default is I 
unspecified. The editor shall use the value of this edit option to determine the type of the display I 
device. I 

The results are unspecified if the user changes the value of the term edit option after editor I 
initialization. I 

terse 

[Default unset] I 

If terse is set, error messages may be less verbose. However, except for this caveat, error 
messages are unspecified. Furthermore, not all error messages need change for different settings 
of this option. 

warn 

[Default set] I 

If warn is set, and the contents of the edit buffer have been modified since they were last I 
completely written, the editor shall write a warning message before certain ! commands (see I 
Escape on page 422). I 
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window 

[Default see text] 

A value used in open and visual mode, by the <control>-B and <control>-F commands, and, in 
visual mode, to specify the number of lines displayed when the screen is repainted. 

If the -w command-line option is not specified, the default value shall be set to the value of the 
LINES environment variable. If the LINES environment variable is empty or null, the default 
shall be the number of lines in the display minus 1. 

Setting the window edit option to zero or to a value greater than the number of lines in the 
display minus 1 (either explicitly or based on the -w option or the LINES environment variable) 
shall cause the window edit option to be set to the number of lines in the display minus 1. 

The baud rate of the terminal line may change the default in an implementation-dependent 
manner. 

wrapmargin, wm 
[Default 0] 

If the value of this edit option is zero, it shall have no effect. 

If not in the POSIX locale, the effect of this edit option is implementation-dependent. 

Otherwise, it shall specify a number of columns from the ending margin of the terminal. 

During open and visual text input modes, for each character for which any part of the character 
is displayed in a column that is less than wrapmargin columns from the ending margin of the 
screen, the editor shall behave as follows: 

1. If the character triggering this event is a <blank> character, it, and all immediately 
preceding <blank> characters on the current line entered during the execution of the 
current text input command, shall be discarded, and the editor shall behave as if the user 
had entered a single <newline> character instead. In addition, if the next user-entered 
character is a <space> character, it shall be discarded as well. 

2. Otherwise, if there are one or more <blank> characters on the current line immediately 
preceding the last group of inserted non-<blank> characters which was entered during the 
execution of the current text input command, the <blank> characters shall be replaced as if 
the user had entered a single <newline> character instead. 

If the autoindent edit option is set, and the events described in 1. or 2. are performed, any 
<blank> characters at or after the cursor in the current line shall be discarded. 

The ending margin shall be determined by the system or overridden by the user, as described for 
COLUMNS in in the ENVIRONMENT VARIABLES section and the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. 

wrapscan, ws 
[Default set] 

If wrapscan is set, searches (the ex / or ? addresses, or open and visual mode /, ?, N, and n 
commands) shall wrap around the beginning or end of the edit buffer; when unset, searches 
shall stop at the beginning or end of the edit buffer. 
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16448 writeany, wa 

16449 [Default unset] I 

16450 If writeany is set, some of the checks performed when executing the ex write commands shall be I 

16451 inhibited, as described in editor option autowrite. I 

16452 EXIT STATUS 

16453 The following exit values shall be returned: 

16454 0 Successful completion. 

16455 >0 An error occurred. 

16456 CONSEQUENCES OF ERRORS 

16457 When any error is encountered and the standard input is not a terminal device file, ex shall not I 

16458 write the file or return to command or text input mode, and shall terminate with a non-zero exit I 

16459 status. I 

16460 Otherwise, when an unrecoverable error is encountered, it shall be equivalent to a SIGHUP I 

16461 asynchronous event. I 

16462 Otherwise, when an error is encountered, the editor shall behave as specified in Command Line I 

16463 Parsing in ex on page 396. I 

16464 APPLICATION USAGE 

16465 If a SIGSEGV signal is received while ex is saving a file, the file might not be successfully saved. 

16466 The next command can accept more than one file, so usage such as: 

16467 next 'Is [abc] * ' 

16468 is valid; it would not be valid for the edit or read commands, for example, because they expect 

16469 only one file and unspecified results occur. 

16470 Application writers should note that this utility need not be provided on systems that do not 

16471 support the User Portability Utilities option. 

16472 EXAMPLES 

16473 None. 

16474 RATIONALE 

16475 The ex/vi specification is based on the historical practice found in the 4 BSD and System V I 

16476 implementations of ex and vi. A freely redistributable implementation of ex/vi, which is I 

16477 tracking IEEE Std. 1003.1-200x fairly closely, and demonstrates the intended changes between I 

16478 historical implementations and IEEE Std. 1003.1-200x, may be obtained from Keith Bostic I 

16479 ( bostic@cs.berkeley.edu ) or by anonymous FTP from: I 

16480 ftp . cs . berkeley . edu : ucb/4bsd/nvi . tar . gz 

16481 A restricted editor (both the historical red utility and modifications to ex) were considered and I 

16482 rejected for inclusion. Neither option provided the level of security that users might expect. I 

16483 It is recognized that ex visual mode and related features would be difficult, if not impossible, to I 

16484 implement satisfactorily on a block-mode terminal, or a terminal without any form of cursor I 

16485 addressing; thus, it is not a mandatory requirement that such features should work on all I 

16486 terminals. It is the intention, however, that an ex implementation should provide the full set of I 

16487 capabilities on all terminals capable of supporting them. I 
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Options 

The -c replacement for +command was inspired by the -e option of sect. Historically, all such 
commands (see edit and next as well) were executed from the last line of the edit buffer. This 
meant, for example, that " + /pattern" would fail unless the wrapscan option was set. 
IEEE Std. 1003.1-200x requires conformance to historical practice. Historically, some 
implementations restricted the ex commands that could be listed as part of the command line 
arguments. For consistency, IEEE Std. 1003.1-200x does not permit these restrictions. 

In historical implementations of the editor, the -R option (and the readonly edit option) only 
prevented overwriting of files; appending to files was still permitted, mapping loosely into the 
csh noclobber variable. Some implementations, however, have not followed this semantic, and 
readonly does not permit appending either. IEEE Std. 1003.1-200x follows the latter practice, 
believing that it is a more obvious and intuitive meaning of readonly. 

The -s option suppresses all interactive user feedback and is useful for editing scripts in batch 
jobs. The list of specific effects is historical practice. The terminal type "incapable of supporting 
open and visual modes" has historically been named "dumb". 

The -t option was required because the ctags utility appears in IEEE Std. 1003.1-200x and the 
option is available in all historical implementations of ex. 

Historically, the ex and vi utilities accepted a -x option, which did encryption based on the 
algorithm found in the historical crypt utility. The -x option for encryption, and the associated 
crypt utility, were omitted because the algorithm used was not specifiable and the export control 
laws of some nations make it difficult to export cryptographic technology. In addition, it did not 
historically provide the level of security that users might expect. 

Standard Input 

An end-of-file condition is not equivalent to an end-of-file character. A common end-of-file 
character, <control>-D, is historically an ex command. 

There was no maximum line length in historical implementations of ex. Specifically, as it was 
parsed in chunks, the addresses had a different maximum length than the file names. Further, 
the maximum line buffer size was declared as |BUFSIZ}, which was different lengths on 
different systems. This version selected the value of |LINE_MAX} to impose a reasonable 
restriction on portable usage of ex and to aid test suite writers in their development of realistic 
tests that exercise this limit. 

Input Files 

It was an explicit decision by the standard developers that a <newline> character be added to 
any file lacking one. It was believed that this feature of ex and vi was relied on by users in order 
to make text files lacking a trailing <newline> more portable. It is recognized that this will 
require a user-specified option or extension for implementations that permit ex and vi to edit 
files of type other than text if such files are not otherwise identified by the system. It was agreed 
that the ability to edit files of arbitrary type can be useful, but it was not considered necessary to 
mandate that an ex or vi implementation be required to handle files other than text files. 

The paragraph in the INPUT FILES section, "By default,...", is intended to close a long-standing 
security problem in ex and vi, that of the "modeline" or "modelines" edit option. This feature 
allows any line in the first or last five lines of the file containing the strings "ex:" or "vi: " 
(and, apparently, "ei : " or "vx : ") to be a line containing editor commands, and ex interprets all 
the text up to the next ' :' or <newline> as a command. Consider the consequences, for 
example, of an unsuspecting user using ex or vi as the editor when replying to a mail message in 
which a line such as: 
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ex:! rm —rf : 

appeared in the signature lines. The standard developers believed strongly that an editor should I 
not by default interpret any lines of a file. Vendors are strongly urged to delete this feature from I 
their implementations of ex and vi. I 

Asynchronous Events I 

The intention of the phrase "complete write" is that the entire edit buffer be written to stable I 
storage. The note regarding temporary files is intended for implementations that use temporary I 
files to back edit buffers unnamed by the user. I 

Historically, SIGQUIT was ignored by ex, but was the equivalent of the Q command in visual I 
mode; that is, it exited visual mode and entered ex mode. IEEE Std. 1003.1-200x permits, but does I 
not require, this behavior. Historically, SIGINT was often used by vi users to terminate text I 
input mode (<control>-C is often easier to enter than <ESC>). Some implementations of vi I 
alerted the terminal on this event, and some did not. IEEE Std. 1003.1-200x requires that SIGINT I 
behave identically to <ESC>, and that the terminal not be alerted. I 

Historically, suspending the ex editor during text input mode was similar to SIGINT, as I 
completed lines were retained, but any partial line discarded, and the editor returned to I 
command mode. IEEE Std. 1003.1-200x is silent on this issue; implementations are encouraged to I 
follow historical practice, where possible. I 

Historically, the vi editor did not treat SIGTSTP as an asynchronous event, and it was therefore I 
impossible to suspend the editor in visual text input mode. There are two major reasons for this. I 
The first is that SIGTSTP is a broadcast signal on UNIX systems, and the chain of events where I 
the shell execs an application that then execs vi usually caused confusion for the terminal state if I 
SIGTSTP was delivered to the process group in the default manner. The second was that most I 
implementations of the UNIX curses package are not reentrant, and the receipt of SIGTSTP at the I 
wrong time will cause them to crash. IEEE Std. 1003.1-200x is silent on this issue; I 
implementations are encouraged to treat suspension as an asynchronous event if possible. I 

Historically, modifications to the edit buffer made before SIGINT interrupted an operation were I 
retained; that is, anywhere from zero to all of the lines to be modified might have been modified I 
by the time the SIGINT arrived. These changes were not discarded by the arrival of SIGINT. I 
IEEE Std. 1003.1-200x permits this behavior, noting that the undo command is required to be able I 
to undo these partially completed commands. I 

The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and SIGTERM is I 
unspecified because some implementations attempt to save the edit buffer in a useful state when I 
other signals are received. I 

Standard Error I 

For ex/vi, diagnostic messages are those messages reported as a result of a failed attempt to I 
invoke ex or vi, such as invalid options or insufficient resources, or an abnormal termination I 
condition. Diagnostic messages should not be confused with the error messages generated by I 
inappropriate or illegal user commands. I 
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Initialization in ex and vi 

If an ex command (other than cd, chdir, or source) has a file name argument, one or both of the 
alternate and current path names will be set. Informally, they are set as follows: 

1. If the ex command is one that replaces the contents of the edit buffer, and it succeeds, the 
current path name will be set to the file name argument (the first file name argument in the 
case of the next command) and the alternate path name will be set to the previous current 
path name, if there was one. 

2. In the case of the file read/write forms of the read and write commands, if there is no 
current path name, the current path name will be set to the file name argument. 

3. Otherwise, the alternate path name will be set to the file name argument. 

For example, :edit too and :recover too, when successful, set the current path name, and, if there 
was a previous current path name, the alternate path name. The commands :write, [command, 
and :edit set neither the current or alternate path names. If the :edit too command were to fail 
for some reason, the alternate path name would be set. The read and write commands set the 
alternate path name to their file argument, unless the current path name is not set, in which case 
they set the current path name to their file arguments. The alternate path name was not 
historically set by the :source command. CA requires conformance to historical practice. 
Implementations adding commands that take file names as arguments are encouraged to set the 
alternate path name as described here. 

Historically, ex and in read the .exrc file in the $HOME directory twice, if the editor was executed 
in the $HOME directory. IEEE Std. 1003.1-200x prohibits this behavior. 

Historically, the 4 BSD ex and vi read the $HOME and local .exrc files if they were owned by the 
real ID of the user, or the sourceany option was set, regardless of other considerations. This was 
a security problem because it is possible to put normal UNIX system commands inside a .exrc 
file. IEEE Std. 1003.1-200x does not specify the sourceany option, and historical implementations 
are encouraged to delete it. 

The .exrc files must be owned by the real ID of the user, and not writeable by anyone other than 
the owner. The appropriate privileges exception is intended to permit users to acquire special 
privileges, but continue to use the .exrc files in their home directories. 

System V Release 3.2 and later vi implementations added the option [no]exrc. The behavior is 
that local .exrc files are read-only if the exrc option is set. The default for the exrc option was off, 
so by default, local .exrc files were not read. The problem this was intended to solve was that 
System V permitted users to give away files, so there is no possible ownership or writeability 
test to ensure that the file is safe. This is still a security problem on systems where users can give 
away files, but there is nothing additional that IEEE Std. 1003.1-200x can do. The 
implementation-dependent exception is intended to permit groups to have local .exrc files that 
are shared by users, by creating pseudo-users to own the shared files. 

IEEE Std. 1003.1-200x does not mention system-wide ex and vi start-up files. While they exist in 
several implementations of ex and vi, they are not present in any implementations considered 
historical practice by IEEE Std. 1003.1-200x. Implementations that have such files should use 
them only if they are owned by the real user ID or an appropriate user (for example, root on 
UNIX systems) and if they are not writeable by any user other than their owner. System-wide 
start-up files should be read before the EXINIT variable, $HOME/.exrc or local .exrc files are 
evaluated. 

Historically, any ex command could be entered in the EXINIT variable or the .exrc file, although 
ones requiring that the edit buffer already contain lines of text generally caused historical 
implementations of the editor to drop core. IEEE Std. 1003.1-200x requires that any ex command 
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be permitted in the EXINIT variable and .exrc files, for simplicity of specification and 
consistency, although many of them will obviously fail under many circumstances. 

The initialization of the contents of the edit buffer uses the phrase "the effect shall be" with 
regard to various ex commands. The intent of this phrase is that edit buffer contents loaded 
during the initialization phase not be lost; that is, loading the edit buffer should fail if the .exrc 
file read in the contents of a file and did not subsequently write the edit buffer. An additional 
intent of this phrase is to specify that the initial current line and column is set as specified for the 
individual ex commands. 

Historically, the -t option behaved as if the tag search were a +command ; that is, it was executed 
from the last line of the file specified by the tag. This resulted in the search failing if the pattern 
was a forward search pattern and the wrapscan edit option was not set. IEEE Std. 1003.1-200x 
does not permit this behavior, requiring that the search for the tag pattern be performed on the 
entire file, and, if not found, that the current line be set to a more reasonable location in the file. 

Historically, the empty edit buffer presented for editing when a file was not specified by the user 
was unnamed. This is permitted by IEEE Std. 1003.1-200x; however, implementations are 
encouraged to provide users a temporary file name for this buffer because it permits them the 
use of ex commands that use the current path name during temporary edit sessions. 

Historically, the file specified using the -t option was not part of the current argument list. This 
practice is permitted by IEEE Std. 1003.1-200x; however, implementations are encouraged to 
include its name in the current argument list for consistency. 

Historically, the -c command was generally not executed until a file that already exists was 
edited. IEEE Std. 1003.1-200x requires conformance to this historical practice. Commands that 
could cause the -c command to be executed include the ex commands edit, next, recover, 
rewind, and tag, and the vi commands <control>-~ and <control>-]. Historically, reading a file 
into an edit buffer did not cause the -c command to be executed (even though it might set the 
current path name) with the exception that it did cause the -c command to be executed if: the 
editor was in ex mode, the edit buffer had no current path name, the edit buffer was empty, and 
no read commands had yet been attempted. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, the -r option was the same as a normal edit session if there was no recovery 
information available for the file. This allowed users to enter: 

vi —r *.c 

and recover whatever files were recoverable. In some implementations, recovery was attempted 
only on the first file named, and the file was not entered into the argument list; in others, 
recovery was attempted for each file named. In addition, some historical implementations 
ignored -r if -t was specified or did not support command line file arguments with the -t option. 
For consistency and simplicity of specification, IEEE Std. 1003.1-200x disallows these special 
cases, and requires that recovery be attempted the first time each file is edited. 

Historically, vi initialized the ' and ' marks, but ex did not. This meant that if the first command 
in ex mode was visual or if an ex command was executed first (for example, vi +10 file), vi was 
entered without the marks being initialized. Because the standard developers believed the marks 
to be generally useful, and for consistency and simplicity of specification, IEEE Std. 1003.1-200x 
requires that they always be initialized if in open or visual mode, or if in ex mode and the edit 
buffer is not empty. Not initializing it in ex mode if the edit buffer is empty is historical practice; 
however, it has always been possible to set (and use) marks in empty edit buffers in open and 
visual mode edit sessions. 
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16666 Addressing 

16667 Historically, ex and vi accepted the additional addressing forms ' \ /' and ' \ ?'. They were 

16668 equivalent to "//" and "71", respectively. They are not required by IEEEStd. 1003.l-200x, 

16669 mostly because nobody can remember whether they ever did anything different historically. 

16670 Historically, ex and vi permitted an address of zero for several commands, and permitted the % 

16671 address in empty files for others. For consistency, IEEE Std. 1003.1-200x requires support for the 

16672 former in the few commands where it makes sense, and disallows it otherwise. In addition, 

16673 because IEEE Std. 1003.l-200x requires that % be logically equivalent to "1,$", it is also 

16674 supported where it makes sense and disallowed otherwise. 

16675 Historically, the % address could not be followed by further addresses. For consistency and 

16676 simplicity of specification, IEEE Std. 1003.1-200x requires that additional addresses be 

16677 supported. 

16678 All of the following are valid addresses: 

16679 + + + Three lines after the current line. 

16680 / re/- One line before the next occurrence of re. 

16681 -2 Two lines before the current line. 

16682 3 - 2 Line one (note intermediate negative address). 

16683 1 2 3 Line six. 

16684 Any number of addresses can be provided to commands taking addresses; for example, 

16685 "1, 2,3, 4, 5p" prints lines 4 and 5, because two is the greatest valid number of addresses 

16686 accepted by the print command. This, in combination with the semicolon delimiter, permits 

16687 users to create commands based on ordered patterns in the file. For example, the command 

16688 3;/foo/;+2print will display the first line after line 3 that contains the pattern foo, plus the next 

16689 two lines. Note that the address 3; must be evaluated before being discarded because the search 

16690 origin for the /too/ command depends on this. 

16691 Historically, values could be added to addresses by including them after one or more <blank> 

16692 characters; for example, 3 - 5p wrote the seventh line of the file, and /too/ 5 was the same as 

16693 /foo/+5. However, only absolute values could be added; for example, 5 /too/ was an error. 

16694 IEEE Std. 1003.1-200x requires conformance to historical practice. Address offsets are separately 

16695 specified from addresses because they could historically be provided to visual mode search 

16696 commands. 

16697 Historically, any missing addresses defaulted to the current line. This was true for leading and 

16698 trailing comma-delimited addresses, and for trailing semicolon-delimited addresses. For 

16699 consistency, IEEE Std. 1003.1-200x requires it for leading semicolon addresses as well. 

16700 Historically, ex and vi accepted the ' '' character as both an address and as a flag offset for 

16701 commands. In both cases it was identical to the character. IEEE Std. 1003.1-200x does not 

16702 require or prohibit this behavior. 

16703 Historically, the enhancements to basic regular expressions could be used in addressing; for 

16704 example, ' ~, and ' . IEEE Std. 1003.l-200x requires conformance to historical 

16705 practice; that is, that regular expression usage be consistent, and that regular expression 

16706 enhancements be supported wherever regular expressions are used. 
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Command Line Parsing in ex 

Historical ex command parsing was even more complex than that described here. 
IEEE Std. 1003.1-200x requires the subset of the command parsing that the standard developers 
believed was documented and that users could reasonably be expected to use in a portable 
fashion, and that was historically consistent between implementations. (The discarded 
functionality is obscure, at best.) Historical implementations will require changes in order to 
comply with IEEE Std. 1003.1-200x; however, users are not expected to notice any of these 
changes. Most of the complexity in ex parsing is to handle three special termination cases: 

1. The !, global, v, and the filter versions of the read and write commands are delimited by 
<newline> characters (they can contain vertical-line characters that are usually shell pipes). 

2. The ex, edit, next, and visual in open and visual mode commands all take ex commands, 
optionally containing vertical-line characters, as their first arguments. 

3. The s command takes a regular expression as its first argument, and uses the delimiting 
characters to delimit the command. 

Historically, vertical-line characters in the +command argument of the ex, edit, next, vi, and 
visual commands, and in the pattern and replacement parts of the s command, did not delimit the 
command, and in the filter cases for read and write, and the !, global, and v commands, they did 
not delimit the command at all. For example, the following commands are all valid: 

:edit +25 ! s/abc/ABC/ file.c 
:s/ | /PIPE/ 

:read !spell % I columnate 
:global/pattern/p | 1 

:s/a/b/ | s/c/d | set 

Historically, empty or «blank» filled lines in .exrc files and sourced files (as well as EX I NIT 
variables and ex command scripts) were treated as default commands; that is, print commands. 
IEEE Std. 1003.1-200x specifically requires that they be ignored when encountered in .exrc and 
sourced files to eliminate a common source of new user error. 

Historically, ex commands with multiple adjacent (or <blank>-separated) vertical lines were 
handled oddly when executed from ex mode. For example, the command I I I <carriage-return>, 
when the cursor was on line 1, displayed lines 2, 3, and 5 of the file. In addition, the command I 
would only display the line after the next line, instead of the next two lines. The former worked 
more logically when executed from vi mode, and displayed lines 2, 3, and 4. 
IEEE Std. 1003.1-200x requires the vi behavior; that is, a single default command and line 
number increment for each command separator, and trailing <newline> characters after 
vertical-line separators are discarded. 

Historically, ex permitted a single extra colon as a leading command character; for example, 
:g/pattern/:p was a valid command. IEEE Std. 1003.1-200x generalizes this to require that any 
number of leading colon characters be stripped. 

Historically, any prefix of the delete command could be followed without intervening <blank> 
characters by a flag character because in the command d p, p is interpreted as the buffer p. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the k command could be followed by the mark name without intervening <blank> 
characters. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the s command could be immediately followed by flag and option characters; for 
example, s/e/E/1 s I sgc3p was a valid command. However, flag characters could not stand alone; 
for example, the commands sp and s 1 would fail, while the command sgp and s gl would 
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succeed. (Obviously, the ' #' flag character was used as a delimiter character if it followed the 
command.) Another issue was that option characters had to precede flag characters even when 
the command was fully specified; for example, the command s/e/E/pg would fail, while the 
command s/e/E/gp would succeed. IEEE Std. 1003.1-200x requires conformance to historical 
practice. 

Historically, the first command name that had a prefix matching the input from the user was the 
executed command; for example, ve, ver, and vers all executed the version command. 
Commands were in a specific order, however, so that a matched append, not abbreviate. 
IEEE Std. 1003.1-200x requires conformance to historical practice. The restriction on command 
search order for implementations with extensions is to avoid the addition of commands such 
that the historical prefixes would fail to work portably. 

Historical implementations of ex and vi did not correctly handle multiple ex commands, 
separated by vertical-line characters, that entered or exited visual mode or the editor. Because 
implementations of vi exist that do not exhibit this failure mode, IEEE Std. 1003.1-200x does not 
permit it. 

The requirement that alphabetic command names consist of all following alphabetic characters 
up to the next non-alphabetic character means that alphabetic command names must be 
separated from their arguments by one or more non-alphabetic characters, normally a <blank> 
or ' !' character, except as specified for the exceptions, the delete, k, and s commands. 

Historically, the repeated execution of the ex default print commands (<control>-D, eof, 
<newline>, <carriage-return>) erased any prompting character and displayed the next lines 
without scrolling the terminal; that is, immediately below any previously displayed lines. This 
provided a cleaner presentation of the lines in the file for the user. IEEE Std. 1003.1-200x does not 
require this behavior because it may be impossible in some situations; however, 
implementations are strongly encouraged to provide this semantic if possible. 

Historically, it was possible to change files in the middle of a command, and have the rest of the 
command executed in the new file; for example: 

:edit +25 file.c I s/abc/ABC/ | 1 

was a valid command, and the substitution was attempted in the newly edited file. 
IEEE Std. 1003.1-200x requires conformance to historical practice. The following commands are 
examples that exercise the ex parser: 

echo 'foo | bar' > filel; echo 'foo/bar' > file2; 
vi 

:edit +1 | s/|/PIPE/ | w filel | e file2 | 1 | s/\//SLASH/ | wq 

Historically, there was no protection in editor implementations to avoid ex global, v, @, or * 
commands changing edit buffers during execution of their associated commands. Because this 
would almost invariably result in catastrophic failure of the editor, and implementations exist 
that do exhibit these problems, IEEE Std. 1003.1-200x requires that changing the edit buffer 
during a global or v command, or during a @ or * command for which there will be more than a 
single execution, be an error. Implementations supporting multiple edit buffers simultaneously 
are strongly encouraged to apply the same semantics to switching between buffers as well. 

The ex command quoting required by IEEE Std. 1003.1-200x is a superset of the quoting in 
historical implementations of the editor. For example, it was not historically possible to escape a 
<blank> character in a file name; for example, :edit foo\\\ bar would report that too many file 
names had been entered for the edit command, and there was no method of escaping a <blank> 
in the first argument of an edit, ex, next, or visual command at all. IEEE Std. 1003.1-200x extends 
historical practice, requiring that quoting behavior be made consistent across all ex commands. 
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except for the map, unmap, abbreviate, and unabbreviate commands, which historically used I 
<control>-V instead of backslashes for quoting. For those four commands, IEEE Std. 1003.1-200x 
requires conformance to historical practice. 

Backslash quoting in ex is non-intuitive. Backslash escapes are ignored unless they escape a 
special character; for example, when performing file argument expansion, the string " \ \ %" is 
equivalent to ' \ %', not " \<current path name>" . This can be confusing for users because 
backslash is usually one of the characters that causes shell expansion to be performed, and 
therefore shell quoting rules must be taken into consideration. Generally, quoting characters are 
only considered if they escape a special character, and a quoting character must be provided for 
each layer of parsing for which the character is special. As another example, only a single 
backslash is necessary for the ' \ 1' sequence in substitute replacement patterns, because the 
character ' 1' is not special to any parsing layer above it. 

<control>-V quoting in ex is slightly different from backslash quoting. In the four commands 
where <control>-V quoting applies (abbreviate, unabbreviate, map, and unmap), any character 
may be escaped by a <control>-V whether it would have a special meaning or not. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historical implementations of the editor did not require delimiters within character classes to be 
escaped; for example, the command :s/[/]// on the string "xxx/yyy" would delete the ' /' from 
the string. IEEE Std. 1003.1-200x disallows this historical practice for consistency and because it 
places a large burden on implementations by requiring that knowledge of regular expressions be 
built into the editor parser. 

Historically, quoting <newline> characters in ex commands was handled inconsistently. In most 
cases, the <newline> always terminated the command, regardless of any preceding escape 
character, because backslash characters did not escape <newline> characters for most ex 
commands. However, some ex commands (for example, s, map, and abbreviation) permitted 
<newline> characters to be escaped (although in the case of map and abbreviation, <control>-V 
characters escaped them instead of backslashes). This was true in not only the command line, 
but also .exrc and sourced files. For example, the command: 

map = foo<control-V><newline>bar 

would succeed, although it was sometimes difficult to get the <control>-V and the inserted 
<newline> passed to the ex parser. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x requires that it be possible to escape <newline> characters in ex commands 
at all times, using backslashes for most ex commands, and using <control>-V characters for the 
map and abbreviation commands. For example, the command print<newline>list is required to 
be parsed as the single command print<newline>list. While this differs from historical practice, 
IEEE Std. 1003.1-200x developers believed it unlikely that any script or user depended on the 
historical behavior. 

Historically, an error in a command specified using the -c option did not cause the rest of the -c 
commands to be discarded. IEEE Std. 1003.1-200x disallows this for consistency with mapped 
keys, the @, global, source, and v commands, the EXINIT environment variable, and the .exrc 
files. 
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Input Editing in ex 

One of the common uses of the historical ex editor is over slow network connections. Editors 
that run in canonical mode can require far less traffic to and from, and far less processing on, the 
host machine, as well as more easily supporting block-mode terminals. For these reasons, 
IEEE Std. 1003.1-200x requires that ex be implemented using canonical mode input processing, 
as was done historically. 

IEEE Std. 1003.1-200x does not require the historical 4 BSD input editing characters "word erase" 
or "literal next". For this reason, it is unspecified how they are handled by ex, although they 
must have the required effect. Implementations that resolve them after the line has been ended 
using a <newline> or <control>-M character, and implementations that rely on the underlying 
system terminal support for this processing, are both conforming. Implementations are strongly 
urged to use the underlying system functionality, if at all possible, for compatibility with other 
system text input interfaces. 

Historically, when the eof character was used to decrement the autoindent level, the cursor 
moved to display the new end of the autoindent characters, but did not move the cursor to a 
new line, nor did it erase the <control>-D character from the line. IEEE Std. 1003.1-200x does not 
specify that the cursor remain on the same line or that the rest of the line is erased; however, 
implementations are strongly encouraged to provide the best possible user interface; that is, the 
cursor should remain on the same line, and any <control>-D character on the line should be 
erased. 

IEEE Std. 1003.1-200x does not require the historical 4 BSD input editing character "reprint", 
traditionally <control>-R, which redisplayed the current input from the user. For this reason, 
and because the functionality cannot be implemented after the line has been terminated by the 
user, IEEE Std. 1003.1-200x makes no requirements about this functionality. Implementations are 
strongly urged to make this historical functionality available, if possible. 

Historically, <control>-Q did not perform a literal next function in ex, as it did in vi. 
IEEE Std. 1003.1-200x requires conformance to historical practice to avoid breaking historical ex 
scripts and .exrc files. 

eof 

Whether the eof character immediately modifies the autoindent characters in the prompt is left 
unspecified so that implementations can conform in the presence of systems that do not support 
this functionality. Implementations are encouraged to modify the line and redisplay it 
immediately, if possible. 

The specification of the handling of the eof character differs from historical practice only in that 
eof characters are not discarded if they follow normal characters in the text input. Historically, 
they were always discarded. 

Command Descriptions in ex 

Historically, several commands (for example, global, v, visual, s, write, wq, yank,!, <, >, &, and 
f were executable in empty files (that is, the default address(es) were 0), or permitted explicit 
addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid range). Addresses of 0, or 
command execution in an empty file, make sense only for commands that add new text to the 
edit buffer or write commands (because users may wish to write empty files). 
IEEE Std. 1003.1-200x requires this behavior for such commands and disallows it otherwise, for 
consistency and simplicity of specification. 

A count to an ex command has been historically corrected to be no greater than the last line in a 
file; for example, in a five-line file, the command l,6print would fail, but the command lprint300 
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would succeed. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the use of flags in ex commands could be obscure. General historical practice was as 
described by IEEE Std. 1003.1-200x, but there were some special cases. For example, the list, 
number, and print commands ignored trailing address offsets; for example, 3p +++# would 
display line 3, and 3 would be the current line after the execution of the command. The open and 
visual commands ignored both the trailing offsets and the trailing flags. Also, flags specified to 
the open and visual commands interacted badly with the list edit option, and setting and then 
unsetting it during the open/visual session would cause vi to stop displaying lines in the 
specified format. For consistency and simplicity of specification, IEEE Std. 1003.1-200x does not 
permit any of these exceptions to the general rule. 

IEEE Std. 1003.1-200x uses the word copy in several places when discussing buffers. This is not 
intended to imply implementation. 

Historically, ex users could not specify numeric buffers because of the ambiguity this would 
cause; for example, in the command 3 delete 2, it is unclear whether 2 is a buffer name or a 
count. IEEE Std. 1003.1-200x requires conformance to historical practice by default, but does not 
preclude extensions. 

Historically, the contents of the unnamed buffer were frequently discarded after commands that 
did not explicitly affect it; for example, when using the edit command to switch files. For 
consistency and simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 

The ex utility did not historically have access to the numeric buffers, and, furthermore, deleting 
lines in ex did not modify their contents. For example, if, after doing a delete in vi, the user 
switched to ex, did another delete, and then switched back to vi, the contents of the numeric 
buffers would not have changed. IEEE Std. 1003.1-200x requires conformance to historical 
practice. Numeric buffers are described in the ex utility in order to confine the description of 
buffers to a single location in IEEE Std. 1003.1-200x. 

The metacharacters that trigger shell expansion in file arguments match historical practice, as 
does the method for doing shell expansion. Implementations wishing to provide users with the 
flexibility to alter the set of metacharacters are encouraged to provide a shellmeta string edit 
option. 

Historically, ex commands executed from vi refreshed the screen when it did not strictly need to 
do so; for example, Mate > /dev/null does not require a screen refresh because the output of the 
UNIX date command requires only a single line of the screen. IEEE Std. 1003.1-200x requires that 
the screen be refreshed if it has been overwritten, but makes no requirements as to how an 
implementation should make that determination. Implementations may prompt and refresh the 
screen regardless. 

Abbreviate 

Historical practice was that characters that were entered as part of an abbreviation replacement 
were subject to map expansions, the showmatch edit option, further abbreviation expansions, 
and so on; that is, they were logically pushed onto the terminal input queue, and were not a 
simple replacement. IEEE Std. 1003.1-200x requires conformance to historical practice. 
Historical practice was that whenever a non-word character (that had not been escaped by a 
<control>-V) was entered after a word character, vi would check for abbreviations. The check 
was based on the type of the character entered before the word character of the word/non-word 
pair that triggered the check. The word character of the word/non-word pair that triggered the 
check and all characters entered before the trigger pair that were of that type were included in 
the check, with the exception of <blank> characters, which always delimited the abbreviation. 
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This means that, for the abbreviation to work, the Iks must end with a word character, there can 
be no transitions from word to non-word characters (or vice versar) other than between the last 
and next-to-last characters in the Ills, and there can be no <blank> characters in the Ills. In 
addition, because of the historical quoting rules, it was impossible to enter a literal <control>-V 
in the Ills. IEEEStd. 1003.l-200x requires conformance to historical practice. Historical 
implementations did not inform users when abbreviations that could never be used were 
entered; implementations are strongly encouraged to do so. 

For example, the following abbreviations will work: 

: ab (p REPLACE 
:ab p REPLACE 
:ab ((p REPLACE 

The following abbreviations will not work: 

:ab ( REPLACE 
:ab (pp REPLACE 

Historical practice is that words on the vi colon command line were subject to abbreviation 
expansion, including the arguments to the abbrev (and more interestingly) the unabbrev 
command. Because there are implementations that do not do abbreviation expansion for the first 
argument to those commands, this is permitted, but not required, by IEEE Std. 1003.1-200x. 
However, the following sequence: 

:ab foo bar 
: ab foo baz 

resulted in the addition of an abbreviation of "baz " for the string "bar" in historical ex/vi, and 
the sequence: 

: ab fool bar 
:ab foo2 bar 
:unabbreviate foo2 

deleted the abbreviation "fool", not "foo2". These behaviors are not permitted by 
IEEE Std. 1003.1-200x because they clearly violate the expectations of the user. 

It was historical practice that <control>-V, not backslash, characters be interpreted as escaping 
subsequent characters in the abbreviate command. IEEE Std. 1003.1-200x requires conformance 
to historical practice; however, it should be noted that an abbreviation containing a <blank> will 
never work. 

Append 

Historically, any text following a vertical-line command separator after an append, change, or 
insert command became part of the insert text. For example, in the command: 

:g/pattern/append|stuff1 

a line containing the text "stuffl" would be appended to each line matching pattern. It was 
also historically valid to enter: 

: append|stuffl 
stuff2 

and the text on the ex command line would be appended along with the text inserted after it. 
There was an historical bug, however, that the user had to enter two terminating lines (the ' .' 
lines) to terminate text input mode in this case. IEEE Std. 1003.1-200x requires conformance to 
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historical practice, but disallows the historical need for multiple terminating lines. 

Change 

See the RATIONALE for the append command. Historical practice for cursor positioning after 
the change command when no text is input, is as described in IEEE Std. 1003.1-200x. However, 
one System V implementation is known to have been modified such that the cursor is positioned 
on the first address specified, and not on the line before the first address. IEEE Std. 1003.1-200x 
disallows this modification for consistency. 

Historically, the change command did not support buffer arguments, although some 
implementations allow the specification of an optional buffer. This behavior is neither required 
nor disallowed by IEEE Std. 1003.1-200x. 

Change Directory 

A common extension in ex implementations is to use the elements of a cdpath edit option as 
prefix directories for path arguments to chdir that are relative path names and that do not have 
' or ". ." as their first component. Elements in the cdpath edit option are colon-separated. 
The initial value of the cdpath edit option is the value of the shell CDPATH environment 
variable. This feature was not included in IEEE Std. 1003.1-200x because it does not exist in any 
of the implementations considered historical practice. 

Copy 

Historical implementations of ex permitted copies to lines inside of the specified range; for 
example, :2,5copy3 was a valid command. IEEE Std. 1003.1-200x requires conformance to 
historical practice. 

Delete 

IEEE Std. 1003.1-200x requires support for the historical parsing of a delete command followed 
by flags, without any intervening <blank> characters. For example: 

ldp Deletes the first line and prints the line that was second. 

ldelep As for ldp. 

Id Deletes the first line, saving it in buffer p. 

Id pll (Pee-one-ell.) Deletes the first line, saving it in buffer p, and listing the line that was 
second. 

Edit 

Historically, any ex command could be entered as a +command argument to the edit command, 
although some (for example, insert and append) were known to confuse historical 
implementations. For consistency and simplicity of specification, IEEE Std. 1003.1-200x requires 
that any command be supported as an argument to the edit command. 

Historically, the command argument was executed with the current line set to the last line of the 
file, regardless of whether the edit command was executed from visual mode or not. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the +command specified to the edit and next commands was delimited by the first 
<blank> character, and there was no way to quote them. For consistency, IEEE Std. 1003.1-200x 
requires that the usual ex backslash quoting be provided. 


Commands and Utilities, Issue 6 


445 




ex 


Utilities 


17017 Historically, specifying the +command argument to the edit command required a file name to be 

17018 specified as well; for example, :edit +100 would always fail. For consistency and simplicity of 

17019 specification, IEEE Std. 1003.1-200x does not permit this usage to fail for that reason. 

17020 Historically, only the cursor position of the last file edited was remembered by the editor. 

17021 IEEE Std. 1003.1-200x requires that this be supported; however, implementations are permitted 

17022 to remember and restore the cursor position for any file previously edited. 

17023 File 

17024 Historical versions of the ex editor file command displayed a current line and number of lines in 

17025 the edit buffer of 0 when the file was empty, while the vi <control>-G command displayed a 

17026 current line and number of lines in the edit buffer of 1 in the same situation. 

17027 IEEE Std. 1003.1-200x does not permit this discrepancy, instead requiring that a message be 

17028 displayed indicating that the file is empty. 

17029 Global 

17030 The two-pass operation of the global and v commands is not intended to imply implementation, 

17031 only the required result of the operation. 

17032 The current line and column are set as specified for the individual ex commands. This 

17033 requirement is cumulative; that is, the current line and column must track across all the 

17034 commands executed by the global or v commands. 

17035 Insert 

17036 See the RATIONALE for the append command. 

17037 Historically, insert could not be used with an address of zero; that is, not when the edit buffer 

17038 was empty. IEEE Std. 1003.1-200x requires that this command behave consistently with the 

17039 append command. 

17040 Join 

17041 The action of the join command in relation to the special characters is only defined for the 

17042 POSIX locale because the correct amount of white space after a period varies; in Japanese none is 

17043 required, in French only a single space, and so on. 

17044 List 

17045 The historical output of the list command was potentially ambiguous. The standard developers 

17046 believed correcting this to be more important than adhering to historical practice, and 

17047 IEEE Std. 1003.1-200x requires unambiguous output. 

17048 Map 

17049 Historically, command mode maps only applied to command names; for example, if the 

17050 character ' x ' was mapped to ' y', the command fx searched for the ' x' character, not the ' y ' 

17051 character. IEEE Std. 1003.1-200x requires this behavior. Historically, entering <control>-V as the 

17052 first character of a vi command was an error. Several implementations have extended the 

17053 semantics of vi such that <control>-V means that the subsequent command character is not 

17054 mapped. This is permitted, but not required, by IEEE Std. 1003.1-200x. Regardless, using 

17055 <control>-V to escape the second or later character in a sequence of characters that might match 

17056 a map command, or any character in text input mode, is historical practice, and stops the entered 

17057 keys from matching a map. IEEE Std. 1003.1-200x requires conformance to historical practice. 
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Historical implementations permitted digits to be used as a map command Ills, but then ignored 
the map. IEEE Std. 1003.1-200x requires that the mapped digits not be ignored. 

The historical implementation of the map command did not permit map commands that were 
more than a single character in length if the first character was printable. This behavior is 
permitted, but not required, by IEEE Std. 1003.1-200x. 

Specifications of "function keys" in the map command were omitted because the historical 
specification of such was too simple to be generally useful in a portable manner. Historical 
practice is that a ' #' followed by a number mapped to that number function key—for example, 
"#3" —was function key 3 for the current terminal, as well as being accessible using the keys 
' #' and ' 3 '. Implementations have extended this semantic to permit users to specify things 
like "#up" and "#page_forward" as well. These extensions are permitted, but not required, 
by IEEE Std. 1003.1-200x. 

Historically, mapped characters were remapped unless the remap edit option was not set, or the 
prefix of the mapped characters matched the mapping characters; for example, in the map: 

:map ab abed 

the characters "ab" were used as is and were not remapped, but the characters "cd" were 
mapped if appropriate. This can cause infinite loops in the vi mapping mechanisms. 
IEEE Std. 1003.1-200x requires conformance to historical practice, and that such loops be 
interruptible. 

Text input maps had the same problems with expanding the Iks for the ex map! and unmap! 
command as did the ex abbreviate and unabbreviate commands. See the RATIONALE for the ex 
abbreviate command. IEEE Std. 1003.1-200x requires similar modification of some historical 
practice for the map and unmap commands, as described for the abbreviate and unabbreviate 
commands. 

Historically, maps that were subsets of other maps behaved differently depending on the order 
in which they were defined. For example: 

:map! ab short 

:map! abc long 

would always translate the characters "ab" to "short", regardless of how fast the characters 
" abc " were entered. If the entry order was reversed: 

:map! abc long 

:map! ab short 

the characters " ab " would cause the editor to pause, waiting for the completing ' c ' character, 
and the characters might never be mapped to "short". For consistency and simplicity of 
specification, IEEE Std. 1003.1-200x requires that the shortest match be used at all times. 

The length of time the editor spends waiting for the characters to complete the Ihs is unspecified 
because the timing capabilities of systems are often inexact and variable, and it may depend on 
other factors such as the speed of the connection. The time should be long enough for the user to 
be able to complete the sequence, but not long enough for the user to have to wait. Some 
implementations of vi have added a keytime option, which permits users to set the number of 
0,1 seconds the editor waits for the completing characters. Because mapped terminal function 
and cursor keys tend to start with an <ESC> character, and <ESC> is the key ending vi text input 
mode, maps starting with <ESC> characters are generally exempted from this timeout period, 
or, at least timed out differently. 
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17102 Mark 

17103 Historically, users were able to set the "previous context" marks explicitly. In addition, the ex 

17104 commands " and " and the vi commands ", ", ", and " all referred to the same mark. In addition, 

17105 the previous context marks were not set if the command, with which the address setting the 

17106 mark was associated, failed. IEEE Std. 1003.1-200x requires conformance to historical practice. 

17107 Historically, if marked lines were deleted, the mark was also deleted, but would reappear if the 

17108 change was undone. IEEE Std. 1003.1-200x requires conformance to historical practice. 

17109 The description of the special events that set the ' and ' marks matches historical practice. For 

17110 example, historically the command laljbl did not set the ' and ' marks, but the command 

17111 /a/,/b/delete did. 

17112 Next 

17113 Historically, any ex command could be entered as a +command argument to the next command, 

17114 although some (for example, insert and append) were known to confuse historical 

17115 implementations. IEEE Std. 1003.1-200x requires that any command be permitted and that it 

17116 behave as specified. The next command can accept more than one file, so usage such as: 

17117 next 'Is [abc] ' 

17118 is valid; it need not be valid for the edit or read commands, for example, because they expect 

17119 only one file name. 

17120 Historically, the next command behaved differently from the :rewind command in that it 

17121 ignored the force flag if the autowrite flag was set. For consistency, IEEE Std. 1003.1-200x does 

17122 not permit this behavior. 

17123 Historically, the next command positioned the cursor as if the file had never been edited before, 

17124 regardless. IEEE Std. 1003.1-200x does not permit this behavior, for consistency with the edit 

17125 command. 

17126 Implementations wanting to provide a counterpart to the next command that edited the 

17127 previous file have used the command previous], which takes no file argument. 

17128 IEEE Std. 1003.1-200x does not require this command. 

17129 Open 

17130 Historically, the open command would fail if the open edit option was not set. 

17131 IEEE Std. 1003.1-200x does not mention the open edit option and does not require this behavior. 

17132 Some historical implementations do not permit entering open mode from open or visual mode, 

17133 only from ex mode. For consistency, IEEE Std. 1003.1-200x does not permit this behavior. 

17134 Historically, entering open mode from the command line (that is, vi +open) resulted in 

17135 anomalous behaviors; for example, the ex file and set commands, and the vi command 

17136 <control>-G did not work. For consistency, IEEE Std. 1003.1-200x does not permit this behavior. 

17137 Historically, the open command only permitted ' /' characters to be used as the search pattern 

17138 delimiter. For consistency, IEEE Std. 1003.1-200x requires that the search delimiters used by the 

17139 s, global, and v commands be accepted as well. 
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Preserve 

The preserve command does not historically cause the file to be considered unmodified for the 
purposes of future commands that may exit the editor. IEEE Std. 1003.1-200x requires 
conformance to historical practice. 

Historical documentation stated that mail was not sent to the user when preserve was executed; 
however, historical implementations did send mail in this case. IEEE Std. 1003.1-200x requires 
conformance to the historical implementations. 

Print 

The writing of NUL by the print command is not specified as a special case because the standard 
developers did not want to require ex to support NUL characters. Historically, characters were 
displayed using the ARPA standard mappings, which are as follows: 

1. Printable characters are left alone. 

2. Control characters less than \177 are represented as ' ~' followed by the character offset 
from the ' @' character in the ASCII map; for example, \007 is represented as ' ' G'. 

3. \ 177 is represented as ' *' followed by ' ?'. 

The display of characters having their eighth bit set was less standard. Existing implementations 
use hex (0x00), octal (\000), and a meta-bit display. (The latter displayed bytes that had their 
eighth bit set as the two characters "M— " followed by the seven-bit display as described above.) 
The latter probably has the best claim to historical practice because it was used for the -v option 
of 4 BSD and 4 BSD-derived versions of the cat utility since 1980. 

No specific display format is required by IEEE Std. 1003.1-200x. 

Explicit dependence on the ASCII character set has been avoided where possible, hence the use 
of the phrase an "implementation-dependent multi-character sequence" for the display of non- 
printable characters in preference to the historical usage of, for instance, " ~ I" for the <tab> 
character. Implementations are encouraged to conform to historical practice in the absence of 
any strong reason to diverge. 

Historically, all ex commands beginning with the letter ' p' could be entered using capitalized 
versions of the commands; for example, P[rint], Pre[serve], and Pu[t] were all valid command 
names. IEEE Std. 1003.1-200x permits, but does not require, this historical practice because 
capital forms of the commands are used by some implementations for other purposes. 

Put 

Historically, an ex put command, executed from open or visual mode, was the same as the open 
or visual mode P command, if the buffer was named and was cut in character mode, and the 
same as the p command if the buffer was named and cut in line mode. If the unnamed buffer 
was the source of the text, the entire line from which the text was taken was usually put, and the 
buffer was handled as if in line mode, but it was possible to get extremely anomalous behavior. 
In addition, using the Q command to switch into ex mode, and then doing a put often resulted in 
errors as well, such as appending text that was unrelated to the (supposed) contents of the 
buffer. For consistency and simplicity of specification, IEEE Std. 1003.1-200x does not permit 
these behaviors. All ex put commands are required to operate in line mode, and the contents of 
the buffers are not altered by changing the mode of the editor. 
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Read 

Historically, an ex read command executed from open or visual mode, executed in an empty file, 
left an empty line as the first line of the file. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x does not permit this behavior. Historically, a read in open or visual mode 
from a program left the cursor at the last line read in, not the first. For consistency, 
IEEE Std. 1003.1-200x does not permit this behavior. 

Historical implementations of ex were unable to undo read commands that read from the output 
of a program. For consistency, IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, the ex and vi message after a successful read or write command specified 
"characters", not "bytes". IEEE Std. 1003.1-200x requires that the number of bytes be displayed, 
not the number of characters, because it may be difficult in multi-byte implementations to 
determine the number of characters read. Implementations are encouraged to clarify the 
message displayed to the user. 

Historically, reads were not permitted on files other than type regular, except that FIFO files 
could be read (probably only because they did not exist when ex and vi were originally written). 
Because the historical ex evaluated read! and read ! equivalently, there can be no optional way 
to force the read. IEEE Std. 1003.1-200x permits, but does not require, this behavior. 

Recover 

Some historical implementations of the editor permitted users to recover the edit buffer contents 
from a previous edit session, and then exit without saving those contents (or explicitly 
discarding them). The intent of IEEE Std. 1003.1-200x in requiring that the edit buffer be treated 
as already modified is to prevent this user error. 

Rewind 

Historical implementations supported the rewind command when the user was editing the first 
file in the list; that is, the file that the rewind command would edit. IEEE Std. 1003.1-200x 
requires conformance to historical practice. 

Substitute 

Historically, ex accepted an r option to the s command. The effect of the r option was to use the 
last regular expression used in any command as the pattern, the same as the ~ command. The r 
option is not required by IEEE Std. 1003.1-200x. Historically, the c and g options were toggled; 
for example, the command :s/abc/def/ was the same as s/abc/def/ccccgggg. For simplicity of 
specification, IEEE Std. 1003.1-200x does not permit this behavior. 

The tilde command is often used to replace the last search RE. For example, in the sequence: 

s/red/blue/ 

/green 


the ~ command is equivalent to: 

s/green/blue/ 

Historically, ex accepted all of the following forms: 

s/abc/def/ 
s/abc/def 
s/abc/ 
s/abc 
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IEEE Std. 1003.1-200x requires conformance to this historical practice. 

The s command presumes that the ' "' character only occupies a single column in the display. 
Much of the ex and vi specification presumes that the <space> character only occupies a single 
column in the display. There are no known character sets for which this is not true. 

Historically, the final column position for the substitute commands was based on previous 
column movements; a search for a pattern followed by a substitution would leave the column 
position unchanged, while a 0 command followed by a substitution would change the column 
position to the first non-<blank>. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x requires that the final column position always be set to the first non- 
<blank>. 

Set 

Historical implementations redisplayed all of the options for each occurrence of the all keyword. 
IEEE Std. 1003.1-200x permits, but does not require, this behavior. 

Tag 

No requirement is made as to where ex and vi shall look for the file referenced by the tag entry. 
Historical practice has been to look for the path found in the tags file, based on the current 
directory. A useful extension found in some implementations is to look based on the directory 
containing the tags file that held the entry, as well. No requirement is made as to which 
reference for the tag in the tags file is used. This is deliberate, in order to permit extensions such 
as multiple entries in a tags file for a tag. 

Because users often specify many different tags files, some of which need not be relevant or exist 
at any particular time, IEEE Std. 1003.1-200x requires that error messages about problem tags 
files be displayed only if the requested tag is not found, and then, only once for each time that 
the tag edit option is changed. 

The requirement that the current edit buffer be unmodified is only necessary if the file indicated 
by the tag entry is not the same as the current file (as defined by the current path name). 
Historically, the file would be reloaded if the file name had changed, as well as if the file name 
was different from the current path name. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x does not permit this behavior, requiring that the name be the only factor in 
the decision. 

Historically, vi only searched for tags in the current file from the current cursor to the end of the 
file, and therefore, if the wrapscan option was not set, tags occurring before the current cursor 
were not found. IEEE Std. 1003.1-200x considers this a bug, and implementations are required to 
search for the first occurrence in the file, regardless. 

Undo 

The undo description deliberately uses the word "modified”. The undo command is not 
intended to undo commands that replace the contents of the edit buffer, such as edit, next, tag, 
or recover. 

Cursor positioning after the undo command was inconsistent in the historical vi, sometimes 
attempting to restore the original cursor position (global, undo, and v commands), and 
sometimes, in the presence of maps, placing the cursor on the last line added or changed instead 
of the first. IEEE Std. 1003.1-200x requires a simplified behavior for consistency and simplicity of 
specification. 
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Version 

The version command cannot be exactly specified since there is no widely-accepted definition of 
what the version information should contain. Implementations are encouraged to do something 
reasonably intelligent. 

Write 

Historically, the ex and vi message after a successful read or write command specified 
"characters", not "bytes". IEEE Std. 1003.1-200x requires that the number of bytes be displayed, 
not the number of characters because it may be difficult in multi-byte implementations to 
determine the number of characters written. Implementations are encouraged to clarify the 
message displayed to the user. 

Implementation-dependent tests are permitted so that implementations can make additional 
checks; for example, for locks or file modification times. 

Historically, attempting to append to a nonexistent file caused an error. It has been left 
unspecified in IEEE Std. 1003.1-200x to permit implementations to let the write succeed, so that 
the append semantics are similar to those of the historical csh. 

Historical vi permitted empty edit buffers to be written. However, since the way vi got around 
dealing with "empty" files was to always have a line in the edit buffer, no matter what, it wrote 
them as files of a single, empty line. IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, ex restored standard output and standard error to their values as of when ex was 
invoked, before writes to programs were performed. This could disturb the terminal 
configuration as well as be a security issue for some terminals. IEEE Std. 1003.1-200x does not 
permit this, requiring that the program output be captured and displayed as if by the ex print 
command. 

Adjust Window 

Historically, the line count was set to the value of the scroll option if the type character was 
end-of-file. This feature was broken on most historical implementations long ago, however, and 
is not documented anywhere. For this reason, IEEE Std. 1003.1-200x is resolutely silent. 

Historically, the z command was <blank> character-sensitive and z + and z - did different 
things than z+ and z- because the type could not be distinguished from a flag. (The commands 
z . and z = were historically invalid.) IEEE Std. 1003.1-200x requires conformance to this 
historical practice. 

Historically, the z command was further <blank> character-sensitive in that the count could not 
be <blank> character-delimited; for example, the commands z= 5 and z- 5 were also invalid. 
Because the count is not ambiguous with respect to either the type character or the flags, this is 
not permitted by IEEE Std. 1003.1-200x. 

Escape 

Historically, ex filter commands only read the standard output of the commands, letting 
standard error appear on the terminal as usual. The vi utility, however, read both standard 
output and standard error. IEEE Std. 1003.1-200x requires the latter behavior for both ex and vi, 
for consistency. 
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Shift Left and Shift Right 

Historically, it was possible to add shift characters to increase the effect of the command; for 
example, «< outdented (or »> indented) the lines 3 levels of indentation instead of the default 
1. IEEE Std. 1003.1-200x requires conformance to historical practice. 

<control>-D 

Historically, the <control>-D command erased the prompt, providing the user with an unbroken 
presentation of lines from the edit buffer. This is not required by IEEE Std. 1003.1-200x; 
implementations are encouraged to provide it if possible. Historically, the <control>-D 
command took, and then ignored, a count. IEEE Std. 1003.1-200x does not permit this behavior. 

Write Line Number 

Historically, the ex = command, when executed in ex mode in an empty edit buffer, reported 0, 
and from open or visual mode, reported 1. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x does not permit this behavior. 

Execute 

Historically, ex did not correctly handle the inclusion of text input commands (that is, append, 
insert, and change) in executed buffers. IEEE Std. 1003.1-200x does not permit this exclusion for 
consistency. 

Historically, the logical contents of the buffer being executed did not change if the buffer itself 
were modified by the commands being executed; that is, buffer execution did not support self¬ 
modifying code. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the @ command took a range of lines, and the @ buffer was executed once per line, 
with the current line (' .') set to each specified line. IEEE Std. 1003.1-200x requires conformance 
to historical practice. 

Some historical implementations did not notice if errors occurred during buffer execution. This, 
coupled with the ability to specify a range of lines for the ex @ command, makes it trivial to 
cause them to drop core. IEEE Std. 1003.1-200x requires that implementations stop buffer 
execution if any error occurs, if the specified line doesn't exist, or if the contents of the edit buffer 
itself are replaced (for example, the buffer executes the ex :edit command). 

Regular Expressions in ex 

Historical practice is that the characters in the replacement part of the last s command—that is, 
those matched by entering a ' ~' in the regular expression—were not further expanded by the 
regular expression engine. So, if the characters contained the string " a., " they would match 
' a' followed by "., " and not ' a' followed by any character. IEEE Std. 1003.1-200x requires 
con formance to historical practice. 

Edit Options in ex 

The following paragraphs describe the historical behavior of some edit options that were not, for 
whatever reason, included in IEEE Std. 1003.1-200x. Implementations are strongly encouraged 
to only use these names if the functionality described here is fully supported. 

extended The extended edit option has been used in some implementations of vi to provide 
extended regular expressions instead of basic regular expressions This option was 
omitted from IEEE Std. 1003.1-200x because it is not widespread historical practice. 
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flash 

The flash edit option historically caused the screen to flash instead of beeping on 
error. This option was omitted from IEEE Std. 1003.1-200x because it is not found 
in some historical implementations. 

17351 

17352 

17353 

hardtabs 

The hardtabs edit option historically defined the number of columns between 
hardware tab settings. This option was omitted from IEEE Std. 1003.1-200x 
because it was believed to no longer be generally useful. 

17354 

17355 

17356 

17357 

modeline 

The modeline (sometimes named modelines) edit option historically caused ex or 
vi to read the five first and last lines of the file for editor commands. This option is 
a security problem, and vendors are strongly encouraged to delete it from 
historical implementations. 

17358 

17359 

17360 

open 

The open edit option historically disallowed the ex open and visual commands. 
This edit option was omitted because these commands are required by 
IEEE Std. 1003.1-200x. 

17361 

17362 

17363 

17364 

17365 

optimize 

The optimize edit option historically expedited text throughput by setting the 
terminal to not do automatic carriage returns when printing more than one logical 
line of output. This option was omitted from IEEE Std. 1003.1-200x because it was 
intended for terminals without addressable cursors, which are rarely, if ever, still 
used. 

17366 

17367 

17368 

ruler 

The ruler edit option has been used in some implementations of vi to present a 
current row/column ruler for the user. This option was omitted from 
IEEE Std. 1003.1-200x because it is not widespread historical practice. 

17369 

17370 

17371 

17372 

sourceany 

The sourceany edit option historically caused ex or vi to source start-up files that 
were owned by users other than the user running the editor. This option is a 
security problem, and vendors are strongly encouraged to remove it from their 
implementations. 

17373 

17374 

17375 

17376 

timeout 

The timeout edit option historically enabled the (now standard) feature of only 
waiting for a short period before returning keys that could be part of a macro. This 
feature was omitted from IEEE Std. 1003.1-200x because its behavior is now 
standard, it is not widely useful, and it was rarely documented. 
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verbose 

The verbose edit option has been used in some implementations of vi to cause vi to 
output error messages for common errors; for example, attempting to move the 
cursor past the beginning or end of the line instead of only alerting the screen. (The 
historical vi only alerted the terminal and presented no message for such errors. 
The historical editor option terse did not select when to present error messages, it 
only made existing error messages more or less verbose.) This option was omitted 
from IEEE Std. 1003.1-200x because it is not widespread historical practice; 
however, implementors are encouraged to use it if they wish to provide error 
messages for naive users. 
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17388 

17389 

17390 

17391 

wraplen 

The wraplen edit option has been used in some implementations of vi to specify an 
automatic margin measured from the left margin instead of from the right margin. 
This is useful when multiple screen sizes are being used to edit a single file. This 
option was omitted from IEEE Std. 1003.1-200x because it is not widespread 
historical practice; however, implementors are encouraged to use it if they add this 
functionality. 
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autoindent, ai 

Historically, the command 0a did not do any autoindentation, regardless of the current 
indentation of line 1. IEEE Std. 1003.1-200x requires that any indentation present in line 1 be 
used. 

autoprint, ap 

Historically, the autoprint edit option was not completely consistent or based solely on 
modifications to the edit buffer. Exceptions were the read command (when reading from a file, 
but not from a filter), the append, change, insert, global, and v commands, all of which were not 
affected by autoprint, and the tag command, which was affected by autoprint. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, the autoprint option only applied to the last of multiple commands entered using 
vertical-bar delimiters; for example, delete <newline> was affected by autoprint, but 
delete I version <newline> was not. IEEE Std. 1003.1-200x requires conformance to historical 
practice. 

autowrite, aw 

Appending the ' !' character to the ex next command to avoid performing an automatic write 
was not supported in historical implementations. IEEE Std. 1003.1-200x requires that the 
behavior match the other ex commands for consistency. 

ignorecase, ic 

Historical implementations of case-insensitive matching (the ignorecase edit option) lead to 
counterintuitive situations when uppercase characters were used in range expressions. 
Historically, the process was as follows: 

1. Take a line of text from the edit buffer. 

2. Convert uppercase to lowercase in text line. 

3. Convert uppercase to lowercase in regular expressions, except in character class 
specifications. 

4. Match regular expressions against text. 

This would mean that, with ignorecase in effect, the text: 

The cat sat on the mat 

would be matched by 

/ "the/ 

but not by: 

/' [A—Z]he/ 

For consistency with other commands implementing regular expressions, IEEE Std. 1003.1-200x 
does not permit this behavior. 
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paragraphs, para 

Earlier versions of IEEE Std. 1003.1-200x made the default paragraphs and sections edit options 
implementation-dependent, arguing they were historically oriented to the UNIX system trojftext 
formatter, and a "portable user" could use the {, }, [[, ]], (, and ) commands in open or visual 
mode and have the cursor stop in unexpected places. IEEE Std. 1003.1-200x specifies their values 
in the POSIX locale because the unusual grouping (they only work when grouped into two 
characters at a time) means that they cannot be used for general purpose movement, regardless. 

readonly 

Implementations are encouraged to provide the best possible information to the user as to the 
read-only status of the file, with the exception that they should not consider the current special 
privileges of the process. This provides users a safety net because they must force the overwrite 
of read-only files, even when running with additional privileges. 

The readonly edit option specification largely conforms to historical practice. The only 
difference is that historical implementations did not notice that the user had set the readonly 
edit option in cases where the file was already marked read-only for some reason, and would 
therefore reinitialize the readonly edit option the next time the contents of the edit buffer were 
replaced. This behavior is disallowed by IEEE Std. 1003.1-200x. 

report 

The requirement that lines copied to a buffer interact differently than deleted lines is historical 
practice. For example, if the report edit option is set to 3, deleting 3 lines will cause a report to be 
written, but 4 lines must be copied before a report is written. 

The requirement that the ex global, v, open, undo, and visual commands present reports based 
on the total number of lines added or deleted during the command execution, and that 
commands executed by the global and v commands not present reports, is historical practice. 
IEEE Std. 1003.1-200x extends historical practice by requiring that buffer execution be treated 
similarly. The reasons for this are two-fold. Historically, only the report by the last command 
executed from the buffer would be seen by the user, as each new report would overwrite the 
last. In addition, the standard developers believed that buffer execution had more in common 
with global and v commands than it did with other ex commands, and should behave similarly, 
for consistency and simplicity of specification. 

showmatch, sm 

The length of time the cursor spends on the matching character is unspecified because the 
timing capabilities of systems are often inexact and variable. The time should be long enough for 
the user to notice, but not long enough for the user to become annoyed. Some implementations 
of vi have added a matchtime option that permits users to set the number of 0,1 second intervals 
the cursor pauses on the matching character. 

showmode 

The showmode option has been used in some historical implementations of ex and vi to display 
the current editing mode when in open or visual mode. The editing modes have generally 
included "command" and "input", and sometimes other modes such as "replace" and 
"change". The string was usually displayed on the bottom line of the screen at the far right-hand 
corner. In addition, a preceding ' *' character often denoted if the contents of the edit buffer had 
been modified. The latter display has sometimes been part of the showmode option, and 
sometimes based on another option. This option was not available in the 4 BSD historical 
implementation of vi, but was viewed as generally useful, particularly to novice users, and is 
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required by IEEE Std. 1003.1-200x. 

The smd shorthand for the showmode option was not present in all historical implementations 
of the editor. IEEE Std. 1003.1-200x requires it, for consistency. 

Not all historical implementations of the editor displayed a mode string for command mode, 
differentiating command mode from text input mode by the absence of a mode string. 
IEEE Std. 1003.1-200x permits this behavior for consistency with historical practice, but 
implementations are encouraged to provide a display string for both modes. 

slowopen 

Historically the slowopen option was automatically set if the terminal baud rate was less than 
1200 baud, or if the baud rate was 1200 baud and the redraw option was not set. The slowopen 
option had two effects. First, when inserting characters in the middle of a line, characters after 
the cursor would not be pushed ahead, but would appear to be overwritten. Second, when 
creating a new line of text, lines after the current line would not be scrolled down, but would 
appear to be overwritten. In both cases, ending text input mode would cause the screen to be 
refreshed to match the actual contents of the edit buffer. Finally, terminals that were sufficiently 
intelligent caused the editor to ignore the slowopen option. IEEE Std. 1003.1-200x permits most 
historical behavior, extending historical practice to require slowopen behaviors if the edit option 
is set by the user. 

tags 

The default path for tags files is left unspecified as implementations may have their own tags 
implementations that do not correspond to the historical ones. The default tags option value 
should probably at least include the file ./tags. 

term 

Historical implementations of ex and vi ignored changes to the term edit option after the initial 
terminal information was loaded. This is permitted by IEEE Std. 1003.1-200x; however, 
implementations are encouraged to permit the user to modify their terminal type at any time. 

terse 

Historically, the terse edit option optionally provided a shorter, less descriptive error message, 
for some error messages. This is permitted, but not required, by IEEE Std. 1003.1-200x. 
Historically, most common visual mode errors (for example, trying to move the cursor past the 
end of a line) did not result in an error message, but simply alerted the terminal. 
Implementations wishing to provide messages for novice users are urged to do so based on the 
edit option verbose, and not terse. 

window 

In historical implementations, the default for the window edit option was based on the baud 
rate as follows: 

1. If the baud rate was less than 1200, the edit option w300 set the window value; for 
example, the line: 

set w300=12 

would set the window option to 12 if the baud rate was less than 1200. 

2. If the baud rate was equal to 1200, the edit option w!200 set the window value. 
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3. If the baud rate was greater than 1200, the edit option w9600 set the window value. 

The w300, wl200, and w9600 options do not appear in IEEE Std. 1003.1-200x because of their 
dependence on specific baud rates. 

In historical implementations, the size of the window displayed by various commands was 
related to, but not necessarily the same as, the window edit option. For example, the size of the 
window was set by the ex command visual 10, but it did not change the value of the window 
edit option. However, changing the value of the window edit option did change the number of 
lines that were displayed when the screen was repainted. IEEE Std. 1003.1-200x does not permit 
this behavior in the interests of consistency and simplicity of specification, and requires that all 
commands that change the number of lines that are displayed do it by setting the value of the 
window edit option. 

wrapmargin, wm 

Historically, the wrapmargin option did not affect maps inserting characters that also had 
associated count s; for example :map K 5aABC DEF. Unfortunately, there are widely used 
maps that depend on this behavior. For consistency and simplicity of specification, 
IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, wrapmargin was calculated using the column display width of all characters on the 
screen. For example, an implementation using "" I" to represent <tab> characters when the list 
edit option was set, where ' "' and ' I' each took up a single column on the screen, would 
calculate the wrapmargin based on a value of 2 for each <tab> character. The number edit 
option similarly changed the effective length of the line as well. IEEE Std. 1003.1-200x requires 
conformance to historical practice. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

ed, sed, stty, vi, the System Interfaces volume of IEEE Std. 1003.1-200x, access () 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

The FUTURE DIRECTIONS section is added. I 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The obsolescent SYNOPSIS is removed, removing the +command and - options. I 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The -1 option is added. 

• In the map command description, the sequence #digit is added. I 

• The directory, edcompatible, redraw, slowopen, and lisp edit options are added. 

The ex utility is extensively changed for alignment with the IEEE P1003.2b draft standard. This I 
includes changes as a result of the PASC Interpretations 1003.2-1992 #31, 38, 49, 50, 51, 52, 55, 56, I 
57,61,62,63,64,65, and 78. I 
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17556 NAME 

17557 expand — convert tabs to spaces 

17558 SYNOPSIS 

17559 UP expand [—t tablist ] [.file . . .] 

17560 

17561 DESCRIPTION 

17562 The expand utility shall write files or the standard input to the standard output with <tab> 

17563 characters replaced with one or more <space> characters needed to pad to the next tab stop. Any 

17564 <backspace> characters shall be copied to the output and cause the column position count for 

17565 tab stop calculations to be decremented; the column position count shall not be decremented 

17566 below zero. 


17567 OPTIONS 

17568 The expand utility shall conform to the System Interface Definitions volume of I 

17569 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

17570 The following option shall be supported: 


17571 

17572 

17573 

17574 

17575 


-t tablist Specify the tab stops. The application shall ensure that the argument tablist I 
consists of a single positive decimal integer or multiple positive decimal integers, I 
separated by <blank> characters or commas, in ascending order. If a single number 
is given, tabs shall be set tablist column positions apart instead of the default 8. If 
multiple numbers are given, the tabs shall be set at those specific column positions. 


17576 

17577 

17578 

17579 


The application shall ensure that each tab-stop position N is an integer value I 
greater than zero, and the list is in strictly ascending order. This is taken to mean I 
that, from the start of a line of output, tabbing to position N shall cause the next 
character output to be in the (N+l)th column position on that line. 


17580 

17581 

17582 


In the event of expand having to process a <tab> character at a position beyond the 
last of those specified in a multiple tab-stop list, the <tab> character shall be 
replaced by a single <space> character in the output. 


17583 OPERANDS 

17584 The following operand shall be supported: 


17585 file The path name of a text file to be used as input. 


17586 STDIN 

17587 See the INPUT FILES section. 


17588 INPUT FILES 

17589 Input files shall be text files. 


17590 ENVIRONMENT VARIABLES 

17591 The following environment variables shall affect the execution of expand: 


17592 

17593 

17594 

17595 

17596 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


17597 

17598 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


17599 

17600 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
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17601 arguments and input files), the processing of <tab> and <space> characters, and 

17602 for the determination of the width in column positions each character would I 

17603 occupy on an output device. I 

17604 LC_MESSAGES 

17605 Determine the locale that should be used to affect the format and contents of 

17606 diagnostic messages written to standard error. 

17607 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

17608 ASYNCHRONOUS EVENTS 

17609 Default. 

17610 STDOUT 

17611 The standard output shall be equivalent to the input files with <tab> characters converted into 

17612 the appropriate number of <space> characters. 

17613 STDERR 

17614 Used only for diagnostic messages. 

17615 OUTPUT FILES 

17616 None. 

17617 EXTENDED DESCRIPTION 

17618 None. 

17619 EXIT STATUS 

17620 The following exit values shall be returned: 

17621 0 Successful completion 

17622 >0 An error occurred. 

17623 CONSEQUENCES OF ERRORS 

17624 The expand utility shall terminate with an error message and non-zero exit status upon 

17625 encountering difficulties accessing one of the file operands. 

17626 APPLICATION USAGE 

17627 Application writers should note that this utility need not be provided on systems that do not 

17628 support the User Portability Utilities option. 

17629 EXAMPLES 

17630 None. 

17631 RATIONALE 

17632 The expand utility is useful for preprocessing text files (before sorting, looking at specific 

17633 columns, and so on) that contain <tab>s. 

17634 See the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.106, Column I 

17635 Position. I 

17636 The tablist option-argument consists of integers in ascending order. Utility Syntax Guideline 8 

17637 mandates that expand shall accept the integers (within the single argument) separated using 

17638 either commas or <blank>s. 

17639 FUTURE DIRECTIONS 

17640 None. 
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17642 

17643 

17644 

17645 

17646 

17647 

17648 

17649 

17650 

17651 


SEE ALSO 

tabs, unexpand 

CHANGE HISTORY 

First released in Issue 4. 


Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The APPLICATION USAGE section is added. 

The obsolescent SYNOPSIS is removed. I 

The LCjCTYPE environment variable description is updated to align with the IEEE P1003.2b I 
draft standard. I 

The normative text is reworded to avoid use of the term "must” for application requirements. I 
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17652 NAME 

17653 expr — evaluate arguments as an expression 

17654 SYNOPSIS 

17655 expr operand 

17656 DESCRIPTION 

17657 The expr utility shall evaluate an expression and write the result to standard output. 

17658 OPTIONS 

17659 None. 

17660 OPERANDS 

17661 The single expression evaluated by expr shall be formed from the operands, as described in the 

17662 EXTENDED DESCRIPTION section. The application shall ensure that each of the expression I 

17663 operator symbols: I 

17664 () | & = >>=<<= != + — */% : 

17665 and the symbols integer and string in the table are provided as separate arguments to expr. I 

17666 STDIN 

17667 Not used. 

17668 INPUT FILES 

17669 None. 


17670 ENVIRONMENT VARIABLES 

17671 The following environment variables shall affect the execution of expr. 


17672 

17673 

17674 

17675 

17676 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


17677 

17678 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


17679 

17680 

17681 

17682 


LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements within regular expressions and by the string 
comparison operators. 


17683 

17684 

17685 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments) and the behavior of character classes within regular expressions. 


17686 LC_MESSAGES 

17687 Determine the locale that should be used to affect the format and contents of 

17688 diagnostic messages written to standard error. 

17689 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


17690 ASYNCHRONOUS EVENTS 

17691 Default. 
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17692 STDOUT 

17693 The expr utility shall evaluate the expression and write the result, followed by a <newline> I 

17694 character, to standard output. I 

17695 STDERR 

17696 Used only for diagnostic messages. 

17697 OUTPUT FILES 

17698 None. 


17699 EXTENDED DESCRIPTION 

17700 The formation of the expression to be evaluated is shown in the following table. The symbols 

17701 expr, exprl, and expr2 represent expressions formed from integer and string symbols and the 

17702 expression operator symbols (all separate arguments) by recursive application of the constructs 

17703 described in the table. The expressions are listed in order of increasing precedence, with equal- 

17704 precedence operators grouped between horizontal lines. All of the operators shall be left- 

17705 associative. 


17706 

17707 

17708 

17709 

17710 

17711 

17712 

17713 

17714 

17715 

17716 

17717 

17718 

17719 

17720 

17721 

17722 

17723 

17724 

17725 

17726 

17727 

17728 

17729 

17730 

17731 

17732 

17733 

17734 

17735 

17736 


Expression 

exprl I exprl 


exprl & exprl 


exprl = exprl 
exprl > exprl 
exprl >= exprl 
exprl < exprl 
exprl <= exprl 
exprl != exprl 
exprl + exprl 
exprl - exprl 
exprl * expr2 
exprl / exprl 

exprl % expr2 

exprl : expr2 
( expr) 


integer 


string 


Description 

Returns the evaluation of exprl if it is neither null nor zero; 
otherwise, returns the evaluation of exprl if it is not null; 
otherwise, zero. 

Returns the evaluation of exprl if neither expression evaluates to 
null or zero; otherwise, returns zero. 

Returns the result of a decimal integer comparison if both 
arguments are integers; otherwise, returns the result of a string 
comparison using the locale-specific collation sequence. The 
result of each comparison is 1 if the specified relationship is true, 
or 0 if the relationship is false. 

Equal. 

Greater than. 

Greater than or equal. 

Less than. 

Less than or equal. 

Not equal. 

Addition of decimal integer-valued arguments. 

Subtraction of decimal integer-valued arguments. 

Multiplication of decimal integer-valued arguments. 

Integer division of decimal integer-valued arguments, producing 
an integer result. 

Remainder of integer division of decimal integer-valued 
arguments. 

Matching expression; see below. 

Grouping symbols. Any expression can be placed within 
parentheses. Parentheses can be nested to a depth of 
j EXPR_NEST_M AX}. 

An argument consisting only of an (optional) unary minus 
followed by digits. 

A string argument; see below. 
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17737 Matching Expression 

17738 The ' :' matching operator shall compare the string resulting from the evaluation of exprl with 

17739 the regular expression pattern resulting from the evaluation of exprl . Regular expression syntax I 

17740 shall be that defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section I 

17741 9.3, Basic Regular Expressions, except that all patterns are anchored to the beginning of the I 

17742 string (that is, only sequences starting at the first character of a string are matched by the regular 

17743 expression) and, therefore, it is unspecified whether ' ~' is a special character in that context. 

17744 Usually, the matching operator shall return a string representing the number of characters 

17745 matched ('O' on failure). Alternatively, if the pattern contains at least one regular expression 

17746 subexpression " [ \ (. . . \) ] ", the string corresponding to " \ 1" shall be returned. 

17747 String Operand 

17748 A string argument is an argument that cannot be identified as an integer argument or as one of 

17749 the expression operator symbols shown in the OPERANDS section. 

17750 The use of string arguments length, substr, index, or match produces unspecified results. 

17751 EXIT STATUS 

17752 The following exit values shall be returned: 

17753 0 The expression evaluates to neither null nor zero. 

17754 1 The expression evaluates to null or zero. 

17755 2 Invalid expression. 

17756 >2 An error occurred. 

17757 CONSEQUENCES OF ERRORS 

17758 Default. 

17759 APPLICATION USAGE 

17760 After argument processing by the shell, expr is not required to be able to tell the difference 

17761 between an operator and an operand except by the value. If " $ a" is ' =', the command: 

17762 expr $a = '=' 

17763 looks like: 

17764 expr = = = 

17765 as the arguments are passed to expr (and they all may be taken as the ' =' operator). The 

17766 following works reliably: 

17767 expr X$a = X= 

17768 Also note that this volume of IEEE Std. 1003.1-200x permits implementations to extend utilities. 

17769 The expr utility permits the integer arguments to be preceded with a unary minus. This means 

17770 that an integer argument could look like an option. Therefore, the portable application must 

17771 employ the "—" construct of Guideline 10 of the System Interface Definitions volume of I 

17772 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines to protect its operands if there is I 

17773 any chance the first operand might be a negative integer (or any string with a leading minus). 

17774 EXAMPLES 

17775 The expr utility has a rather difficult syntax: 

17776 • Many of the operators are also shell control operators or reserved words, so they have to be 

17777 escaped on the command line. 
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• Each part of the expression is composed of separate arguments, so liberal usage of <blank> 
characters is required. For example: 


Invalid 

Valid 

expr 1+2 
expr "1 + 2" 
expr 1 + (2*3) 

expr 1+2 
expr 1+2 

expr 1 + \( 2 \* 3 \) 


In many cases, the arithmetic and string features provided as part of the shell command 
language are easier to use than their equivalents in expr. Newly written scripts should avoid 
expr in favor of the new features within the shell; see Section 2.5 on page 43 and Section 2.6.4 on 
page 56. 

The following command: 
a=$ (expr $a + 1 ) 
adds 1 to the variable a. 

The following command, for " $a" equal to either /usr/abc/file or just file: 

expr $a : '.*/\(.*\)' \| $a 

returns the last segment of a path name (that is, file). Applications should avoid the character 
' /' used alone as an argument: expr may interpret it as the division operator. 

The following command: 

expr " //$ a" : ' .*/\ ( .*\)' 

is a better representation of the previous example. The addition of the "//" characters 
eliminates any ambiguity about the division operator and simplifies the whole expression. Also 
note that path names may contain characters contained in the IFS variable and should be quoted 
to avoid having " $a" expand into multiple arguments. 

The following command: 

expr "$VAR" : 

returns the number of characters in VAR. 

RATIONALE 

In an early proposal, EREs were used in the matching expression syntax. This was changed to 
BREs to avoid breaking historical applications. 

The use of a leading circumflex in the BRE is unspecified because many historical 
implementations have treated it as a special character, despite their system documentation. For 
example: 

expr foo : "foo expr "foo : "foo 

return 3 and 0, respectively, on those systems; their documentation would imply the reverse. 
Thus, the anchoring condition is left unspecified to avoid breaking historical scripts relying on 
this undocumented feature. 

FUTURE DIRECTIONS 

None. 
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17817 SEE ALSO 

17818 Section 2.6.4 

17819 CHANGE HISTORY 

17820 First released in Issue 2. 

17821 Issue 4 

17822 Aligned with the ISO/IEC 9945-2:1993 standard. 

17823 Issue 5 

17824 FUTURE DIRECTIONS section added. I 

17825 Issue 6 I 

17826 The expr utility is aligned with the IEEE P1003.2b draft standard, to include resolution of PASC I 

17827 Interpretation 1003.2-92 #104. I 

17828 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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17829 NAME 

17830 false — return false value 

17831 SYNOPSIS 

17832 false 

17833 DESCRIPTION 

17834 Th e false utility shall return with a non-zero exit code. 

17835 OPTIONS 

17836 None. 

17837 OPERANDS 

17838 None. 

17839 STDIN 

17840 Not used. 

17841 INPUT FILES 

17842 None. 

17843 ENVIRONMENT VARIABLES 

17844 None. 

17845 ASYNCHRONOUS EVENTS 

17846 Default. 

17847 STDOUT 

17848 Not used. 

17849 STDERR 

17850 None. 

17851 OUTPUT FILES 

17852 None. 

17853 EXTENDED DESCRIPTION 

17854 None. 

17855 EXIT STATUS 

17856 Th e false utility always shall exit with a value other than zero. 

17857 CONSEQUENCES OF ERRORS 

17858 Default. 

17859 APPLICATION USAGE 

17860 None. 

17861 EXAMPLES 

17862 None. 

17863 RATIONALE 

17864 None. 

17865 FUTURE DIRECTIONS 

17866 None. 

17867 SEE ALSO 

17868 true 
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17869 CHANGE HISTORY 

17870 First released in Issue 2. 

17871 Issue 4 

17872 Aligned with the ISO/IEC 9945-2:1993 standard. 
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NAME 

fc — process the command history list 

SYNOPSIS 

up fc [—r][—e editor] [first[last]] 

fc —1[—nr] [first[last] ] 
fc —s[old=new][first] 


DESCRIPTION 

The fc utility shall list, or shall edit and re-execute, commands previously entered to an 
interactive sh. 

The command history list shall reference commands by number. The first number in the list is 
selected arbitrarily. The relationship of a number to its command shall not change except when 
the user logs in and no other process is accessing the list, at which time the system may reset the 
numbering to start the oldest retained command at another number (usually 1). When the 
number reaches an implementation-dependent upper limit, which shall be no smaller than the 
value in HISTSIZE or 32 767 (whichever is greater), the shell may wrap the numbers, starting the 
next command with a lower number (usually 1). However, despite this optional wrapping of 
numbers, fc shall maintain the time-ordering sequence of the commands. For example, if four 
commands in sequence are given the numbers 32 766, 32 767, 1 (wrapped), and 2 as they are 
executed, command 32 767 is considered the command previous to 1, even though its number is 
higher. 

When commands are edited (when the -1 option is not specified), the resulting lines shall be 
entered at the end of the history list and then re-executed by sh. The/c command that caused the 
editing shall not be entered into the history list. If the editor returns a non-zero exit status, this 
shall suppress the entry into the history list and the command re-execution. Any command line I 
variable assignments or redirection operators used with fc shall affect both the/c command itself I 
as well as the command that results; for example: 

fc —s — —1 2>/dev/null 

reinvokes the previous command, suppressing standard error for both fc and the previous 
command. 

OPTIONS 

The/c utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-e editor Use the editor named by editor to edit the commands. The editor string is a utility 

name, subject to search via the PATH variable (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables). The value in I 
the FCEDIT variable shall be used as a default when -e is not specified. If FCEDIT I 
is null or unset, ed shall be used as the editor. 

-1 (The letter ell.) List the commands rather than invoking an editor on them. The 

commands shall be written in the sequence indicated by the first and last operands, 
as affected by -r, with each command preceded by the command number. 

-n Suppress command numbers when listing with -1. 

-r Reverse the order of the commands listed (with -1) or edited (with neither -1 nor 

-s). 
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-s Reexecute the command without invoking an editor. 

OPERANDS 

The following operands shall be supported: 
first, last 

Select the commands to list or edit. The number of previous commands that can be 
accessed shall be determined by the value of the HISTSIZE variable. The value of 
first or last or both shall be one of the following: 

[+]number A positive number representing a command number; command 
numbers can be displayed with the -1 option. 

-number A negative decimal number representing the command that was 
executed number of commands previously. For example, -1 is the 
immediately previous command. 

string A string indicating the most recently entered command that begins 

with that string. If the old =nezv operand is not also specified with -s, 
the string form of the first operand cannot contain an embedded 
equal sign. 

When the synopsis form with -s is used: 

• If first is omitted, the previous command shall be used. 

For the synopsis forms without -s: 

• If last is omitted, last shall default to the previous command when -1 is 
specified; otherwise, it shall default to first. 

• If first and last are both omitted, the previous 16 commands shall be listed or 
the previous single command shall be edited (based on the -1 option). 

• li first and last are both present, all of the commands from first to last shall be 
edited (without -1) or listed (with -1). Editing multiple commands shall be 
accomplished by presenting to the editor all of the commands at one time, each 
command starting on a new line. If first represents a newer command than last, 
the commands shall be listed or edited in reverse sequence, equivalent to using 
-r. For example, the following commands on the first line are equivalent to the 
corresponding commands on the second: 

fc -r 10 20 fc 30 40 

fc 20 10 fc -r 40 30 

• When a range of commands is used, it shall not be an error to specify first or last 
values that are not in the history list ;fc shall substitute the value representing 
the oldest or newest command in the list, as appropriate. For example, if there 
are only ten commands in the history list, numbered 1 to 10: 

fc -1 
fc 1 99 

shall list and edit, respectively, all ten commands. 

old=new Replace the first occurrence of string old in the commands to be re-executed by the 
string new. 
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17959 STDIN 

17960 Not used. 

17961 INPUT FILES 

17962 None. 


17963 ENVIRONMENT VARIABLES 

17964 The following environment variables shall affect the execution of fc: 


17965 

17966 

17967 


FCEDIT This variable, when expanded by the shell, shall determine the default value for 
the -e editor option's editor option-argument. If FCEDIT is null or unset, ed shall be 
used as the editor. 


17968 

17969 

17970 

17971 

17972 

17973 

17974 

17975 

17976 

17977 

17978 

17979 

17980 

17981 

17982 

17983 

17984 

17985 

17986 

17987 

17988 

17989 

17990 

17991 

17992 

17993 

17994 


HISTFILE Determine a path name naming a command history file. If the HISTFILE variable is 
not set, the shell may attempt to access or create a file .sh_history in the directory 
referred to by the HOME environment variable. If the shell cannot obtain both read 
and write access to, or create, the history file, it shall use an unspecified 
mechanism that allows the history to operate properly. (References to history 
"file" in this section shall be understood to mean this unspecified mechanism in 
such cases.) An implementation may choose to access this variable only when 
initializing the history file; this initialization shall occur when fc or sh first attempt 
to retrieve entries from, or add entries to, the file, as the result of commands issued 
by the user, the file named by the ENV variable, or implementation-dependent I 
system start-up files. (The initialization process for the history file can be I 
dependent on the system start-up files, in that they may contain commands that I 
effectively preempt the user's settings of HISTFILE and HISTSIZE. For example, 
function definition commands are recorded in the history file, unless the set -o 
nolog option is set. If the system administrator includes function definitions in I 
some system start-up file called before the ENV file, the history file is initialized I 
before the user gets a chance to influence its characteristics.) In some historical 
shells, the history file is initialized just after the ENV file has been processed. 
Therefore, it is implementation-dependent whether changes made to HISTFILE 
after the history file has been initialized are effective. Implementations may 
choose to disable the history list mechanism for users with appropriate privileges 
who do not set HISTFILE ; the specific circumstances under which this occurs are 
implementation-dependent. If more than one instance of the shell is using the 
same history file, it is unspecified how updates to the history file from those shells 
interact. As entries are deleted from the history file, they shall be deleted oldest 
first. It is unspecified when history file entries are physically removed from the 
history file. 


17995 

17996 

17997 

17998 

17999 

18000 
18001 


HISTSIZE Determine a decimal number representing the limit to the number of previous 
commands that are accessible. If this variable is unset, an unspecified default 
greater than or equal to 128 shall be used. The maximum number of commands in 
the history list is unspecified, but shall be at least 128. An implementation may 
choose to access this variable only when initializing the history file, as described 
under HISTFILE. Therefore, it is unspecified whether changes made to HISTSIZE 
after the history file has been initialized are effective. 


18002 

18003 

18004 

18005 

18006 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 
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18007 

18008 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


18009 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

18010 characters (for example, single-byte as opposed to multi-byte characters in 

18011 arguments and input files). 

18012 LC_MESSAGES 

18013 Determine the locale that should be used to affect the format and contents of 

18014 diagnostic messages written to standard error. 

18015 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

18016 ASYNCHRONOUS EVENTS 

18017 Default. 


18018 STDOUT 

18019 When the -1 option is used to list commands, the format of each command in the list shall be as 

18020 follows: 


18021 "%d\t%s\n", <line number>, <command> 

18022 If both the -1 and -n options are specified, the format of each command shall be: 

18023 "\t%s\n", <command> 

18024 If the <command> consists of more than one line, the lines after the first shall be displayed as: 

18025 "\t%s\n", <continued~command> 

18026 STDERR 

18027 Used only for diagnostic messages. 

18028 OUTPUT FILES 

18029 None. 

18030 EXTENDED DESCRIPTION 

18031 None. 

18032 EXIT STATUS 

18033 The following exit values shall be returned: 

18034 0 Successful completion of the listing. 

18035 >0 An error occurred. 

18036 Otherwise, the exit status shall be that of the commands executed by fc. 

18037 CONSEQUENCES OF ERRORS 

18038 Default. 

18039 APPLICATION USAGE 

18040 Since editors sometimes use file descriptors as integral parts of their editing, redirecting their file 

18041 descriptors as part of the fc command can produce unexpected results. For example, if vi is the 

18042 FCEDIT editor, the command: 

18043 fc — s | more 

18044 does not work correctly on many systems. 

18045 Users on windowing systems may want to have separate history files for each window by 

18046 setting HISTFILE as follows: 
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18047 

18048 

18049 

18050 

18051 

18052 

18053 

18054 

18055 

18056 

18057 

18058 

18059 

18060 

18061 

18062 

18063 

18064 

18065 

18066 

18067 

18068 

18069 

18070 

18071 

18072 

18073 

18074 

18075 

18076 

18077 

18078 

18079 

18080 

18081 

18082 

18083 

18084 

18085 

18086 

18087 

18088 

18089 

18090 

18091 
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HISTFILE=$HOME/.sh_hist$$ 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

This utility is based on the fc built-in of the KomShell. 

An early proposal specified the -e option as [-e editor [old = new ] ], which is not historical 
practice. Historical practice in fc of either [-e editor] or [-e - [ old= new ] ] is acceptable, but not 
both together. To clarify this, a new option -s was introduced replacing the [-e -]. This resolves 
the conflict and makes fc conform to the Utility Syntax Guidelines. 

HISTFILE Users on windowing systems may want to have separate history files for each 
window by setting HISTFILE as follows: 

HISTFILE=$HOME/.sh_hist$$ 

Some implementations of the KomShell check for the superuser and do not create 
a history file unless HISTFILE is set. This is done primarily to avoid creating 
unlinked files in the root file system when logging in during single-user mode. 
HISTFILE must be set for the superuser to have history. 

HISTSIZE Needed to limit the size of history files. It is the intent of the standard developers 
that when two shells share the same history file, commands that are entered in one 
shell shall be accessible by the other shell. Because of the difficulties of 
synchronization over a network, the exact nature of the interaction is unspecified. 

The initialization process for the history file can be dependent on the system start-up files, in I 
that they may contain commands that effectively preempt the settings the user has for HISTFILE I 
and HISTSIZE. For example, function definition commands are recorded in the history file. If the 
system administrator includes function definitions in some system start-up file called before the I 
ENV file, the history file is initialized before the user can influence its characteristics. In some 
historical shells, the history file is initialized just after the ENV file has been processed. Because 
of these situations, the text requires the initialization process to be implementation-dependent. 

Consideration was given to omitting the fc utility in favor of the command line editing feature in I 
sh. For example, in vi editing mode, typing " <ESC> v" is equivalent to: 

EDITOR=vi fc 

However, the fc utility allows the user the flexibility to edit multiple commands simultaneously 
(such as fc 10 20) and to use editors other than those supported by sh for command line editing. I 

In the KomShell, the alias r ("re-do") is preset to fc -e - (equivalent to the POSIX/c -s). This is 
probably an easier command name to remember than fc ("fix command"), but it does not meet 
the Utility Syntax Guidelines. Renaming fc to hist or redo was considered, but since this 
description closely matches historical KomShell practice already, such a renaming was seen as 
gratuitous. Users are free to create aliases whenever odd historical names such as fc, awk, cat, 
grep, or pace are standardized by POSIX. 

Command numbers have no ordering effects; they are like serial numbers. The -r option and 
-number operand address the sequence of command execution, regardless of serial numbers. So, 
for example, if the command number wrapped back to 1 at some arbitrary point, there would be 
no ambiguity associated with traversing the wrap point. For example, if the command history 
were: 


474 Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


fc 


18092 3 2 7 6 6: echo 1 

18093 32767: echo 2 

18094 1 : echo 3 

18095 the number -2 refers to command 32 767 because it is the second previous command, regardless 

18096 of serial number. 

18097 FUTURE DIRECTIONS 

18098 None. 

18099 SEE ALSO 

18100 sh 

18101 CHANGE HISTORY 

18102 First released in Issue 4. 

18103 Issue 5 

18104 FUTURE DIRECTIONS section added. 

18105 Issue 6 

18106 This utility is now marked as part of the User Portability Utilities option. 

18107 In the ENVIRONMENT VARIABLES section, the text "user's home directory" is updated to 

18108 "directory referred to by the HOME environment variable". 
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18109 NAME 

18110 fg — run jobs in the foreground 

18111 SYNOPSIS 

18112 up fg [ job_id] 

18113 

18114 DESCRIPTION 

18115 If job control is enabled (see the description of set -m), thefg utility shall move a background job 

18116 from the current environment (see Section 2.12 on page 90) into the foreground. 

18117 Using fg to place a job into the foreground shall remove its process ID from the list of those 

18118 "known in the current shell execution environment"; see Section 2.9.3.1 on page 74. 

18119 OPTIONS 

18120 None. 

18121 OPERANDS 

18122 The following operand shall be supported: 


18123 

job_id 

Specify the job to be run as a foreground job. If no job_id operand is given, the 

18124 


job_id for the job that was most recently suspended, placed in the background or 

18125 


run as a background job, shall be used. The format of job_id is described in the 

18126 


System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.207, Job 

18127 


Control Job ID. 

18128 STDIN 



18129 

Not used. 


18130 INPUT FILES 


18131 

None. 


18132 ENVIRONMENT VARIABLES 

18133 

The following environment variables shall affect the execution of fg: 

18134 

LANG 

Provide a default value for the internationalization variables that are unset or null. 

18135 


If LANG is unset or null, the corresponding value from the implementation- 

18136 


dependent default locale shall be used. If any of the internationalization variables 

18137 


contains an invalid setting, the utility shall behave as if none of the variables had 

18138 


been defined. 

18139 

LC_ALL 

If set to a non-empty string value, override the values of all the other 

18140 


internationalization variables. 

18141 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 

18142 


characters (for example, single-byte as opposed to multi-byte characters in 

18143 


arguments). 

18144 

LC_MESSAGES 

18145 


Determine the locale that should be used to affect the format and contents of 

18146 


diagnostic messages written to standard error. 

18147 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

18148 ASYNCHRONOUS EVENTS 

18149 

Default. 
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18150 STDOUT 

18151 The/y utility shall write the command line of the job to standard output in the following format: 

18152 "%s\n", <command> 

18153 STDERR 

18154 Used only for diagnostic messages. 

18155 OUTPUT FILES 

18156 None. 

18157 EXTENDED DESCRIPTION 

18158 None. 

18159 EXIT STATUS 

18160 The following exit values shall be returned: 

18161 0 Successful completion. 

18162 >0 An error occurred. 

18163 CONSEQUENCES OF ERRORS 

18164 If job control is disabled, the fg utility shall exit with an error and no job shall be placed in the 

18165 foreground. 

18166 APPLICATION USAGE 

18167 The fg utility does not work as expected when it is operating in its own utility execution 

18168 environment because that environment has no applicable jobs to manipulate. See the 

18169 APPLICATION USAGE section for bg on page 243. For this reason, jy is generally implemented 

18170 as a shell regular built-in. 

18171 Application writers should note that this utility need not be provided on systems that do not 

18172 support the User Portability Utilities option. 

18173 EXAMPLES 

18174 None. 

18175 RATIONALE 

18176 The extensions to the shell specified in this volume of IEEE Std. 1003.1-200x have mostly been 

18177 based on features provided by the KomShell. The job control features provided by bg,fg, and jobs 

18178 are also based on the KomShell. The standard developers examined the characteristics of the C 

18179 shell versions of these utilities and found that differences exist. Despite widespread use of the C 

18180 shell, the KomShell versions were selected for this volume of IEEE Std. 1003.1-200x to maintain a 

18181 degree of uniformity with the rest of the KomShell features selected (such as the very popular I 

18182 command line editing features). I 

18183 FUTURE DIRECTIONS 

18184 None. 

18185 SEE ALSO 

18186 bg, kill, jobs, wait 

18187 CHANGE HISTORY 

18188 First released in Issue 4. 

18189 Issue 6 

18190 This utility is now marked as part of the User Portability Utilities option. 

18191 The APPLICATION USAGE section is added. 
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The JC marking is removed from the SYNOPSIS since job control is mandatory is this issue. 
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18193 NAME 

18194 file — determine file type 

18195 SYNOPSIS 

18196 UP file [—dhi] [— M file ] [—m file] file . . . 

18197 


18198 DESCRIPTION 

18199 The file utility shall perform a series of tests on each specified file in an attempt to classify it: 


18200 

18201 

18202 


1. If the file is not a regular file, its file type shall be identified. The file types directory, FIFO, 
block special, and character special shall be identified as such. Other implementation- 
dependent file types may also be identified. 


18203 


2. If the file is a regular file, and: 


18204 


a. The file is zero-length, it shall be identified as an empty file. 


18205 

18206 
18207 


b. The file is not zero-length, file shall examine an initial segment of the file and shall 
make a guess at identifying its contents or whether it is an executable binary file. 
(The answer is not guaranteed to be correct.) 


18208 If file does not exist, cannot be read, or its file status could not be determined, the output shall 

18209 indicate that the file was processed, but that its type could not be determined. 

18210 If file is a symbolic link, by default the link shall be resolved and file shall test the type of file 

18211 referenced by the symbolic link. 


18212 OPTIONS 

18213 The file utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

18214 Section 12.2, Utility Syntax Guidelines. 

18215 The following options shall be supported by the implementation: 


18216 

-d 

18217 

-h 

18218 


18219 



Apply any default system tests to the file. 

When a symbolic link is encountered, identify the file as a symbolic link. If -h is 
not specified and file is a symbolic link that refers to a nonexistent file, file shall 
identify the file as a symbolic link, as if -h had been specified. 


18220 -i 

18221 
18222 


If a file is a regular file, do not attempt to classify the type of the file further, but 
identify the file as specified in the STDOUT section, using a <type> string that 
contains the string regular file. 


18223 

18224 

18225 


-Mfile Specify the name of a file containing tests that shall be applied to a file in order to 
classify it (see the EXTENDED DESCRIPTION). No default system tests shall be 
applied. 


18226 -m file Specify the name of a file containing tests that shall be applied to a file in order to 

18227 classify it (see the EXTENDED DESCRIPTION). 


18228 If multiple instances of the -m, -d, or -M options are specified, the concatenation of the tests 

18229 specified, in the order specified, shall be the set of tests that are applied. If a -M option is 

18230 specified, no tests other than those specified using the -d, -M, and -m options shall be applied 

18231 to the file. If neither the -d nor -M options are specified, any default system tests shall be 

18232 applied after any tests specified using the -m option. 
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18233 OPERANDS 

18234 The following operand shall be supported: 

18235 file A path name of a file to be tested. 

18236 STDIN 

18237 Not used. 

18238 INPUT FILES 

18239 Th efile can be any file type. 

18240 ENVIRONMENT VARIABLES 


18241 

The following environment variables shall affect the execution of file: 

18242 

18243 

18244 

18245 

18246 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

18247 

18248 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

18249 

18250 

18251 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

18252 

18253 

18254 

18255 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

18256 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


18257 ASYNCHRONOUS EVENTS 

18258 Default. 

18259 STDOUT 

18260 In the POSIX locale, the following format shall be used to identify each operand,//7e specified: I 

18261 "%s: %s\n", <file>, <type> 

18262 The values for <type> are unspecified, except that in the POSIX locale, if file is identified as one I 

18263 of the types listed in the following table, <type> shall contain (but is not limited to) the 

18264 corresponding string. Each space shown in the strings shall be exactly one <space> character. I 
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18265 

18266 

18267 

18268 

18269 

18270 

18271 

18272 

18273 

18274 

18275 

18276 

18277 

18278 

18279 

18280 
18281 

18282 

18283 

18284 

18285 

18286 

18287 

18288 

18289 

18290 

18291 

18292 

18293 

18294 

18295 

18296 

18297 

18298 

18299 

18300 

18301 

18302 

18303 

18304 

18305 

18306 

18307 

18308 

18309 


Table 4-8 File Utility Output Strings 


It file is a: 

<type> shall contain the string: 

Directory 

directory 

FIFO 

fifo 

Block special 

block special 

Character special 

character special 

Executable binary 

executable 

Empty regular file 

empty 

Symbolic link 

symbolic link to 

ar archive library (see ar) 

archive 

Extended cpio format (see pax) 

cpio archive 

Extended tar format (see ustar in pax) 

tar archive 

Shell script 

commands text 

C-language source 

c program text 

FORTRAN source 

fortran program text 


It file is identified as a symbolic link (see -h), the following alternative output format shall be 
used: 

"%s: %s %s\n", <file>, <type>, <contents of link>” 

If the file named by the file operand does not exist or cannot be read, the string " cannot open " 
shall be included as part of the <type> field, but this shall not be considered an error that affects 
the exit status. If the type of the file named by the file operand cannot be determined, the string 
" data " shall be included as part of the <type> field, but this shall not be considered an error that 
affects the exit status. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

A file specified as an option-argument to the -m or -M options shall contain one test per line, 
which shall be applied to the file. If the test succeeds, the message field of the line shall be 
printed and no further tests shall be applied, with the exception that tests on immediately 
following lines beginning with a single ' >' character shall be applied. 

Each line shall be composed of the following four <blank>-separated fields: 

offset An unsigned number (optionally preceded by a single ' >' character) specifying 

the offset, in bytes, of the value in the file that is to be compared against the value 
field of the line. If the file is shorter than the specified offset, the test shall fail. 

If the offset begins with the character ' >', the test contained in the line shall not be 
applied to the file unless the test on the last line for which the offset did not begin 
with a ' >' was successful. By default, the offset shall be interpreted as an unsigned 
decimal number. With a leading Ox or OX, the offset shall be interpreted as a 
hexadecimal number; otherwise, with a leading 0, the offset shall be interpreted as 
an octal number. 

type The type of the value in the file to be tested. The type shall consist of the type 

specification characters c, d, f, s, and u, specifying character, signed decimal, 
floating point, string, and unsigned decimal, respectively. 
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18310 

18311 

18312 

18313 

18314 

18315 

18316 

18317 

18318 

18319 

18320 

18321 

18322 

18323 

18324 

18325 

18326 

18327 

18328 

18329 

18330 

18331 

18332 

18333 

18334 

18335 

18336 

18337 

18338 

18339 

18340 

18341 

18342 

18343 

18344 

18345 

18346 

18347 

18348 

18349 

18350 

18351 

18352 

18353 

18354 

18355 

18356 
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The type string shall be interpreted as the bytes from the file starting at the 
specified offset and including the same number of bytes specified by the value field. 
If insufficient bytes remain in the file past the offset to match the value field, the test 
shall fail. 

The type specification characters d, f, and u can be followed by an optional 
unsigned decimal integer that specifies the number of bytes represented by the 
type. The type specification character f can be followed by an optional F, D, or L, 
indicating that the value is of type float, double, or long double, respectively. The 
type specification characters d and u can be followed by an optional C, S, I, or L, 
indicating that the value is of type char, short, int, or long, respectively. 

The default number of bytes represented by the type specifiers d, f, and u shall 
correspond to their respective C-language types as follows. If the system claims 
conformance to the C-Language Development Utilities option, those specifiers 
shall correspond to the default sizes used in the c89 utility. Otherwise, the default 
sizes shall be implementation-dependent. 

For the type specifier characters d and u, the default number of bytes shall 
correspond to the size of the basic integral data type of the implementation. For 
these specifier characters, the implementation shall support values of the optional 
number of bytes to be converted corresponding to the number of bytes in the C- 
language types char, short, int, or long. These numbers can also be specified by an 
application as the characters C, S, I, and L, respectively. The byte order used when 
interpreting numeric values is implementation-dependent, but shall correspond to 
the order in which a constant of the corresponding type is stored in memory on the 
system. 

For the type specifier f, the default number of bytes shall correspond to the number 
of bytes in the basic double precision floating-point data type of the underlying 
implementation. The implementation shall support values of the optional number 
of bytes to be converted corresponding to the number of bytes in the C-language 
types float, double, and long double. These numbers can also be specified by an 
application as the characters F, D, and L, respectively. 

All type specifiers, except for s, can be followed by a mask specifier of the form 
Scnumber. The mask value shall be AND'ed with the value before the comparison 
with the value from the file is made. By default, the mask shall be interpreted as an 
unsigned decimal number. With a leading Ox or OX, the mask shall be interpreted 
as an unsigned hexadecimal number; otherwise, with a leading 0, the mask shall be 
interpreted as an unsigned octal number. 

The strings byte, short, long, and string shall also be supported as type fields, 
being interpreted as dC, dS, dL, and s, respectively. 

value The value to be compared with the value from the file. 

Any value that contains a character that is not a digit, other than a leading sign 
(' +' or ) or a leading Ox or OX, shall be interpreted as a string. The test shall 
succeed only when a string value exactly matches the bytes from the file. 

If the value is a string, it can contain the following sequences: 

\character The backslash-escape sequences as specified in the System 

Interface Definitions volume of IEEE Std. 1003.1-200x, Table 5-1, 
Escape Sequences and Associated Actions (' W, ' \a', ' \b', 
' \ f', ' \n', ' \ r', ' \t', ' \v'). The results of using any other 
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18357 

18358 

18359 

18360 

18361 

18362 

18363 

18364 

18365 

18366 

18367 

18368 

18369 

18370 

18371 

18372 

18373 

18374 

18375 

18376 

18377 

18378 

18379 

18380 

18381 

18382 

18383 


character, other than an octal digit, following the backslash are 
unspecified. 

\octal Octal sequences that can be used to represent characters with 

specific coded values. An octal sequence shall consist of a 
backslash followed by the longest sequence of one, two, or three 
octal-digit characters (01234567). If the size of a byte on the 
system is greater than 9 bits, the valid escape sequence used to 
represent a byte is implementation-dependent. 

By default, any value that is not a string shall be interpreted as a signed decimal 
number. Any such value, with a leading Ox or OX, shall be interpreted as an 
unsigned hexadecimal number; otherwise, with a leading zero, the value shall be 
interpreted as an unsigned octal number. 

If the value is not a string, it can be preceded by a character indicating the 
comparison to be performed. Permissible characters and the comparisons they 
specify are as follows: 

= The test shall succeed if the value from the file equals the value field. 

< The test shall succeed if the value from the file is less than the value field. 

> The test shall succeed if the value from the file is greater than the value field. 

& The test shall succeed if all of the bits in the value field are set in the value 

from the file. 

The test shall succeed if at least one of the bits in the value field is not set in the 
value from the file. 

x The test shall succeed if there is any value in the file. 

message The message to be printed if the test succeeds. The message shall be interpreted 
using the notation for the printf formatting specification; see printf. If the value 
field was a string, then the value from the file shall be the argument for the printf 
formatting specification; otherwise, the value from the file shall be the argument. 


18384 EXIT STATUS 

18385 The following exit values shall be returned: 

18386 0 Successful completion. 

18387 >0 An error occurred. 


18388 CONSEQUENCES OF ERRORS 

18389 Default. 

18390 APPLICATION USAGE 

18391 The file utility can only be required to guess at many of the file types because only exhaustive 

18392 testing can determine some types with certainty. For example, binary data on some systems 

18393 might match the initial segment of an executable or a tar archive. 

18394 Note that the table indicates that the output contains the stated string. Systems may add text 

18395 before or after the string. For executables, as an example, the machine architecture and various 

18396 facts about how the file was link-edited may be included. 

18397 Application writers should note that this utility need not be provided on systems that do not 

18398 support the User Portability Utilities option. 
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18399 EXAMPLES 

18400 Determine whether an argument is a binary executable file: 

18401 file "$1" | grep — Fq executable && 

18402 printf "%s is executable.\n" "$1" 

18403 RATIONALE 

18404 The -f option was omitted because the same effect can (and should) be obtained using the xargs 

18405 utility. 

18406 Historical versions of the file utility attempt to identify the following types of files: symbolic link, 

18407 directory, character special, block special, socket, tar archive, cpio archive, SCCS archive, archive 

18408 library, empty, compress output, pack output, binary data, C source, FORTRAN source, assembler 

18409 source, nrojf/trojf/eqn/tbl source troff output, shell script, C shell script, English text, ASCII text, 

18410 various executables, APL workspace, compiled terminfo entries, and CURSES screen images. 

18411 Only those types that are reasonably well specified in POSIX or are directly related to POSIX 

18412 utilities are listed in the table. 

18413 Implementations that support symbolic links are encouraged to use the string "symbolic 

18414 link" to identify them. 

18415 Historical systems have used a "magic file" named /etc/magic to help identify file types. Because 

18416 it is generally useful for users and scripts to be able to identify special file types, the -m flag and 

18417 a portable format for user-created magic files has been specified. No requirement is made that an 

18418 implementation of file use this method of identifying files, only that users be permitted to add 

18419 their own classifying tests. 

18420 In addition, three options have been added to historical practice. The -d flag has been added to 

18421 permit users to cause their tests to follow any default system tests. The -i flag has been added to 

18422 permit users to test portably for regular files in shell scripts. The -M flag has been added to 

18423 permit users to ignore any default system tests. 

18424 The historical -c option was omitted as not particularly useful to users or portable shell scripts. 

18425 In addition, a reasonable implementation of the file utility would report any errors found each 

18426 time the magic file is read. 

18427 The historical format of the magic file was the same as that specified by the Rationale in the 

18428 previous version of IEEE Std. 1003.1-200x for the offset, value, and message fields; however, it 

18429 used less precise type fields than the format specified by the current normative text. The new 

18430 type field values are a superset of the historical ones. 

18431 The following is an example magic file: 


18432 

0 

short 

070707 

cpio archive 

18433 

0 

short 

0143561 

Byte-swapped cpio archive 

18434 

0 

string 

070707 

ASCII cpio archive 

18435 

0 

long 

0177555 

Very old archive 

18436 

0 

short 

0177545 

Old archive 

18437 

0 

short 

017437 

Old packed data 

18438 

0 

string 

\037\036 

Packed data 

18439 

0 

string 

\377\037 

Compacted data 

18440 

0 

string 

\037\235 

Compressed data 

18441 

>2 

byte&0x80 

>0 

Block compressed 

18442 

>2 

byte&Oxlf 

X 

%d bits 

18443 

0 

string 

\032\001 

Compiled Terminfo Entry 

18444 

0 

short 

0433 

Curses screen image 

18445 

0 

short 

0434 

Curses screen image 
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18446 

0 

string 

<ar> 

System V Release 1 archive 

18447 

0 

string 

!<arch>\n_.SYMDEF 

Archive random library 

18448 

0 

string 

!<arch> 

Archive 

18449 

0 

string 

ARF_BEGARF 

PHIGS clear text archive 

18450 

0 

long 

0xl37A2950 

Scalable OpenFont binary 

18451 

0 

long 

0xl37A2951 

Encrypted scalable OpenFont binary 


18452 FUTURE DIRECTIONS 

18453 None. 

18454 SEE ALSO 

18455 Is 

18456 CHANGE HISTORY 

18457 First released in Issue 4. 

18458 Issue 6 

18459 This utility is now marked as part of the User Portability Utilities option. I 

18460 Options and an EXTENDED DESCRIPTION are added as specified in the IEEE P1003.2b draft I 

18461 standard. I 
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18462 NAME 

18463 find — find files 

18464 SYNOPSIS 

18465 find [—H | —L] path . . . [operand_expression . . .] 

18466 DESCRIPTION 

18467 The find utility shall recursively descend the directory hierarchy from each file specified by path, 

18468 evaluating a Boolean expression composed of the primaries described in the OPERANDS section 

18469 for each file encountered. 

18470 The find utility shall be able to descend to arbitrary depths in a file hierarchy and shall not fail 

18471 due to path length limitations (unless a path operand specified by the application exceeds 

18472 {PATH_MAX} requirements). 

18473 The find utility shall detect infinite loops; that is, entering a previously visited directory that is an 

18474 ancestor of the last file encountered. When it detects an infinite loop, find shall write a 

18475 diagnostic message to standard error and shall either recover its position in the hierarchy or 

18476 terminate. 

18477 OPTIONS 

18478 The find utility shall conform to the System Interface Definitions volume of 

18479 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

18480 The following options shall be supported by the implementation: 

18481 -H Cause the file information and file type evaluated for each symbolic link 

18482 encountered on the command line to be those of the file referenced by the link, and 

18483 not the link itself. If the referenced file does not exist, the file information and type 

18484 shall be for the link itself. File information for all symbolic links not on the 

18485 command line shall be that of the link itself. 

18486 -L Cause the file information and file type evaluated for each symbolic link to be 

18487 those of the file referenced by the link, and not the link itself. 

18488 Specifying more than one of the mutually-exclusive options -H and -L shall not be considered 

18489 an error. The last option specified shall determine the behavior of the utility. 

18490 OPERANDS 

18491 The following operands shall be supported: 

18492 The path operand is a path name of a starting point in the directory hierarchy. 

18493 The first argument that starts with a ', or is a ' !' or a ' (', and all subsequent arguments 

18494 shall be interpreted as an expression made up of the following primaries and operators. In the 

18495 descriptions, wherever n is used as a primary argument, it shall be interpreted as a decimal 

18496 integer optionally preceded by a plus (' +') or minus (' -') sign, as follows: 

18497 +n More than n. 

18498 n Exactly n . 

18499 -n Less than n . 

18500 The following primaries shall be supported: 

18501 -name pattern 

18502 The primary shall evaluate as true if the basename of the file name being examined 

18503 matches pattern using the pattern matching notation described in Section 2.13 on 

18504 page 92. 
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18505 

18506 

18507 

18508 

18509 

18510 

18511 

18512 

18513 

18514 

18515 

18516 

18517 

18518 

18519 

18520 

18521 

18522 

18523 

18524 

18525 

18526 

18527 

18528 

18529 

18530 

18531 

18532 

18533 

18534 MAN 

18535 

18536 

18537 

18538 

18539 

18540 

18541 

18542 

18543 

18544 

18545 

18546 

18547 

18548 

18549 

18550 


-nouser 


-nogroup 


-xdev 


-prune 


The primary shall evaluate as true if the file belongs to a user ID for which the 
getpivuid() function defined in the System Interfaces volume of 

IEEE Std. 1003.1-200x (or equivalent) returns NULL. 

The primary shall evaluate as true if the file belongs to a group ID for which the 
getgrgid() function defined in the System Interfaces volume of 

IEEE Std. 1003.1-200x (or equivalent) returns NULL. 

The primary always shall evaluate as true; it shall cause find not to continue 
descending past directories that have a different device ID ( st_dev , see the stat () 
function defined in the System Interfaces volume of IEEE Std. 1003.1-200x). If any 
-xdev primary is specified, it shall apply to the entire expression even if the -xdev 
primary would not normally be evaluated. 

The primary always shall evaluate as true; it shall cause find not to descend the 
current path name if it is a directory. If the -depth primary is specified, the -prune 
primary shall have no effect. 


-perm [~]mode 

The mode argument is used to represent file mode bits. It shall be identical in 
format to the symbolicjnode operand described in chmod on page 273, and shall be 
interpreted as follows. To start, a template shall be assumed with all file mode bits 
cleared. An op symbol of ' +' shall set the appropriate mode bits in the template; 

shall clear the appropriate bits; '=' shall set the appropriate mode bits, 
without regard to the contents of process' file mode creation mask. The op symbol 
of cannot be the first character of mode; this avoids ambiguity with the 
optional leading hyphen. Since the initial mode is all bits off, there are not any 
symbolic modes that need to use ' —' as the first character. 


If the hyphen is omitted, the primary shall evaluate as true when the file 
permission bits exactly match the value of the resulting template. 


Otherwise, if mode is prefixed by a hyphen, the primary shall evaluate as true if at 
least all the bits in the resulting template are set in the file permission bits. 

-perm [~]onnm 

If the hyphen is omitted, the primary shall evaluate as true when the file 
permission bits exactly match the value of the octal number onum and only the bits 
corresponding to the octal mask 07777 shall be compared. (See the description of 
the octal mode in chmod on page 273.) Otherwise, if onnm is prefixed by a hyphen, 
the primary shall evaluate as true if at least all of the bits specified in onnm that are 
also set in the octal mask 07777 are set. 

-type c The primary shall evaluate as true if the type of the file is c, where c is ' b', ' c', 

' d', M', ' p', or ' f' for block special file, character special file, directory, I 
symbolic link, FIFO, or regular file, respectively. I 

-links n The primary shall evaluate as true if the file has n links. 

-user nname The primary shall evaluate as true if the file belongs to the user uname. If uname is 
a decimal integer and the getpwnam{) (or equivalent) function does not return a 
valid user name, uname shall be interpreted as a user ID. 


-group gname 

The primary shall evaluate as true if the file belongs to the group gname. If gname 
is a decimal integer and the getgrnam{) (or equivalent) function does not return a 
valid group name, gname shall be interpreted as a group ID. 
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18551 

18552 

18553 

18554 

18555 

18556 

18557 

18558 

18559 

18560 

18561 

18562 

18563 

18564 

18565 

18566 

18567 

18568 

18569 

18570 

18571 

18572 

18573 

18574 

18575 

18576 

18577 

18578 

18579 

18580 

18581 

18582 

18583 

18584 

18585 

18586 

18587 

18588 

18589 

18590 

18591 

18592 

18593 

18594 

18595 


-size n[ c] 


-atime n 


-ctime n 


-mtime n 


The primary shall evaluate as true if the file size in bytes, divided by 512 and 
rounded up to the next integer, is n. If n is followed by the character ' c', the size 
shall be in bytes. 

The primary shall evaluate as true if the file access time subtracted from the 
initialization time, divided by 86 400 (with any remainder discarded), is n. 

The primary shall evaluate as true if the time of last change of file status 
information subtracted from the initialization time, divided by 86400 (with any 
remainder discarded), is n. 

The primary shall evaluate as true if the file modification time subtracted from the 
initialization time, divided by 86 400 (with any remainder discarded), is n. 


-exec utility_name [ argument .. .] ; 

The primary shall evaluate as true if the invoked utility utility_name returns a zero 
value as exit status. The end of the primary expression shall be punctuated by a 
semicolon. A utility_name or argument containing only the two characters " { }" 
shall be replaced by the current path name. If a utility_name or argument string 
contains the two characters " {}", but not just the two characters " { }", it is 
implementation-dependent whether find replaces those two characters with the 
current path name or uses the string without change. The current directory for the 
invocation of utility_name shall be the same as the current directory when the find 
utility was started. If the utility_name names any of the special built-in utilities in 
Section 2.14 on page 96, the results are undefined. 


-ok utility_name [argument ...]; 

The -ok primary shall be equivalent to -exec, except that find shall request 
affirmation of the invocation of utility_name using the current file as an argument 
by writing to standard error as described in the STDERR section. If the response on 
standard input is affirmative, the utility shall be invoked. Otherwise, the command 
shall not be invoked and the value of the -ok operand shall be false. 

-print The primary always shall evaluate as true; it shall cause the current path name to 

be written to standard output. 

-newerfile The primary shall evaluate as true if the modification time of the current file is 
more recent than the modification time of the file named by the path name file. 

-depth The primary shall always evaluate as true; it shall cause descent of the directory 
hierarchy to be done so that all entries in a directory are acted on before the 
directory itself. If a -depth primary is not specified, all entries in a directory shall 
be acted on after the directory itself. If any -depth primary is specified, it shall 
apply to the entire expression even if the -depth primary would not normally be 
evaluated. 


The primaries can be combined using the following operators (in order of decreasing 
precedence): 

( expression ) True if expression is true. 

! expression Negation of a primary; the unary NOT operator. 
expression [-a] expression 

Conjunction of primaries; the AND operator is implied by the juxtaposition of two 
primaries or made explicit by the optional -a operator. The second expression 
shall not be evaluated if the first expression is false. 
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18597 

18598 

18599 

18600 
18601 

18602 

18603 

18604 

18605 

18606 

18607 

18608 

18609 

18610 
18611 

18612 

18613 

18614 

18615 

18616 

18617 

18618 

18619 

18620 
18621 
18622 

18623 

18624 

18625 

18626 

18627 

18628 

18629 

18630 

18631 

18632 

18633 

18634 

18635 

18636 

18637 


expression -o expression 

Alternation of primaries; the OR operator. The second expression shall not be 
evaluated if the first expression is true. 

If no expression is present, -print shall be used as the expression. Otherwise, if the given 
expression does not contain any of the primaries -exec, -ok, or -print, the given expression shall 
be effectively replaced by: 

( given_expression ) —print 

The -user, -group, and -newer primaries each shall evaluate their respective arguments only 
once. 


STDIN 

If the -ok primary is used, the response shall be read from the standard input. An entire line 

shall be read as the response. Otherwise, the standard input shall not be used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of find: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements used in the pattern matching notation for the -n 
option and in the extended regular expression defined for the yesexpr locale 
keyword in the LC_MESSAGES category. 

LC_CTYPE This variable determines the locale for the interpretation of sequences of bytes of 
text data as characters (for example, single-byte as opposed to multi-byte 
characters in arguments), the behavior of character classes within the pattern 
matching notation used for the -n option, and the behavior of character classes 
within regular expressions used in the extended regular expression defined for the 
yesexpr locale keyword in the LC_MESSAGES category. 

LC_MESSAGES 

Determine the locale for the processing of affirmative responses that should be 
used to affect the format and contents of diagnostic messages written to standard 
error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Determine the location of the utility_name for the -exec and -ok primaries, as I 

described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 8, Environment Variables. I 
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18638 ASYNCHRONOUS EVENTS 

18639 Default. 

18640 STDOUT 

18641 The -print primary shall cause the current path names to be written to standard output. The 

18642 format shall be: 


18643 "%s\n", <path> 

18644 STDERR 

18645 The -ok primary shall write a prompt to standard error containing at least the utility_name to be 

18646 invoked and the current path name. In the POSIX locale, the last non-<blank> character in the 

18647 prompt shall be ' ?'. The exact format used is unspecified. 

18648 Otherwise, the standard error shall be used only for diagnostic messages. 

18649 OUTPUT FILES 

18650 None. 

18651 EXTENDED DESCRIPTION 

18652 None. 

18653 EXIT STATUS 

18654 The following exit values shall be returned: 

18655 0 All path operands were traversed successfully. 

18656 >0 An error occurred. 


18657 CONSEQUENCES OF ERRORS 

18658 Default. 


18659 APPLICATION USAGE 

18660 When used in operands, pattern matching notation, semicolons, opening parentheses, and 

18661 closing parentheses are special to the shell and must be quoted (see Section 2.2 on page 36). 

18662 The bit that is traditionally used for sticky (historically 01000) is specified in the -perm primary 

18663 using the octal number argument form. Since this bit is not defined by this volume of 

18664 IEEE Std. 1003.1-200x, applications must not assume that it actually refers to the traditional 

18665 sticky bit. 

18666 EXAMPLES 


18667 

18668 

18669 

18670 

18671 

18672 

18673 

18674 

18675 

18676 

18677 

18678 


1. The following commands are equivalent: 

find . 

find . —print 

They both write out the entire directory hierarchy from the current directory. 

2. The following command: 

find / \( —name tmp —o —name '*.xx' \) —atime +7 —exec rm {} \; 

removes all files named tmp or ending in .xx that have not been accessed for seven or more 
24-hour periods. 

3. The following command: 

find . —perm —o+w,+s 

prints (-print is assumed) the names of all files in or below the current directory, with all 
of the file permission bits S_ISUID, S_ISGID, and S_IWOTH set. 
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18679 

18680 

18681 

18682 

18683 

18684 

18685 

18686 

18687 

18688 

18689 

18690 

18691 

18692 

18693 

18694 

18695 

18696 

18697 

18698 

18699 

18700 

18701 

18702 

18703 

18704 

18705 

18706 

18707 

18708 

18709 

18710 

18711 

18712 

18713 

18714 

18715 

18716 

18717 

18718 

18719 

18720 

18721 


4. The following command: 

find . —name SCCS —prune —o —print 

recursively prints path names of all files in the current directory and below, but skips 
directories named SCCS and files in them. 

5. The following command: 

find . —print —name SCCS —prune 

behaves as in the previous example, but prints the names of the SCCS directories. 

6. The following command is roughly equivalent to the -nt extension to test: 

if [ —n "$(find filel —prune —newer file2)" ]; then 
printf %s\\n "filel is newer than file2" 
fi 

7. The descriptions of -atime, -ctime, and -mtime use the terminology n "24-hour periods". 
For example, a file accessed at 23:59 is selected by: 

find . —atime —1 —print 

at 00:01 the next day (less than 24 hours later, not more than one day ago); the midnight 
boundary between days has no effect on the 24-hour calculation. 

RATIONALE 

The -a operator was retained as an optional operator for compatibility with historical shell 
scripts, even though it is redundant with expression concatenation. 

The descriptions of the modifier on the mode and onum arguments to the -perm primary 
agree with historical practice on BSD and System V implementations. System V and BSD 
documentation both describe it in terms of checking additional bits; in fact, it uses the same bits, 
but checks for having at least all of the matching bits set instead of having exactly the matching 
bits set. 

The exact format of the interactive prompts is unspecified. Only the general nature of the 
contents of prompts are specified because: 

• Implementations may desire more descriptive prompts than those used on historical 
implementations. 

• Since the historical prompt strings do not terminate with <newline>s, there is no portable 
way for another program to interact with the prompts of this utility via pipes. 

Therefore, an application using this prompting option relies on the system to provide the most 
suitable dialog directly with the user, based on the general guidelines specified. 

The -name file operand was changed to use the shell pattern matching notation so that find is 
consistent with other utilities using pattern matching. 

For the -type c operand, implementors of symbolic links should consider 1 (the letter ell) for 
symbolic links. Implementations that support sockets also use -type s for sockets. 
Implementations planning to add options to allow find to follow symbolic links or treat them as 
special files should consider the -follow primary implemented in BSD and System V Release 4 
as a guide. 

The -size operand refers to the size of a file, rather than the number of blocks it may occupy in 
the file system. The intent is that the st_size field defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x should be used, not the st_blocks found in historical implementations. 
There are at least two reasons for this: 
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1. In both System V and BSD , find only uses s t_size in size calculations for the operands 
specified by this volume of IEEE Std. 1003.1-200x. (BSD uses stjblocks only when 
processing the -Is primary.) 

2. Users usually think of file size in terms of bytes, which is also the unit used by the Is utility 
for the output from the -1 option. (In both System V and BSD, Is uses st_size for the -1 
option size field and uses stjblocks for the Is -s calculations. This volume of 
IEEE Std. 1003.1-200x does not specify Is -s.) 

The descriptions of -atime, -ctime, and -mtime were changed from the SVID description of n 
"days” to "24-hour periods". The description is also different in terms of the exact timeframe for 
the n case (versus the +n or —n), but it matches all known historical implementations. It refers to 
one 24-hour period in the past, not any time from the beginning of that period to the current 
time. For example, -atime 3 is true if the file was accessed any time in the period from 72 hours 
to 48 hours ago. 

Historical implementations do not modify " { }" when it appears as a substring of an -exec or 
-ok utility_name or argument string. There have been numerous user requests for this extension, 
so this volume of IEEE Std. 1003.1-200x allows the desired behavior. At least one recent 
implementation does support this feature, but encountered several problems in managing 
memory allocation and dealing with multiple occurrences of " { }" in a string while it was being 
developed, so it is not yet required behavior. 

Assuming the presence of -print was added to correct a historical pitfall that plagues novice 
users, it is entirely upward-compatible from the historical System V find utility. In its simplest 
form (find directory), it could be confused with the historical BSD fast find. The BSD developers 
agreed that adding -print as a default expression was the correct decision and have added the 
fast find functionality within a new utility called locate. 

Historically, the -L option was implemented using the primary -follow. The -H and -L options 
were added for two reasons. First, they offer a finer granularity of control and consistency with 
other programs that walk file hierarchies. Second, the -follow primary always evaluated to true. 
As they were historically really global variables that took effect before the traversal began, some 
valid expressions had unexpected results. An example is the expression -print -o -follow. 
Because -print always evaluates to true, the standard order of evaluation implies that -follow 
would never be evaluated. This was never the case. Historical practice for the -follow primary, 
however, is not consistent. Some implementations always follow symbolic links on the 
command line whether -follow is specified or not. Others follow symbolic links on the 
command line only if -follow is specified. Both behaviors are provided by the -H and -L 
options, but scripts using the current -follow primary would be broken if the -follow option is 
specified to work either way. 

Since the -L option resolves all symbolic links and the -type l primary is true for symbolic links 
that still exist after symbolic links have been resolved, the command: 

find —L . —type 1 

prints a list of symbolic links reachable from the current directory that do not resolve to 
accessible files. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

chmod, pax, sh, test, the System Interfaces volume of IEEE Std. 1003.1-200x, stat () 
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18767 CHANGE HISTORY 

18768 First released in Issue 2. 

18769 Issue 4 

18770 Aligned with the ISO/IEC 9945-2:1993 standard. 

18771 Issue 5 

18772 FUTURE DIRECTIONS section added. 

18773 Issue 6 

18774 The following new requirements on POSIX implementations derive from alignment with the 

18775 Single UNIX Specification: 

18776 • The -perm [-]onnm primary is supported. 

18777 The find utility is aligned with the IEEE P1003.2b draft standard, to include processing of I 

18778 symbolic links and changes to the description of the atime, ctime, and mtime operands. I 
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18779 

18780 

18781 

18782 

18783 

18784 

18785 

18786 

18787 

18788 

18789 

18790 

18791 

18792 

18793 

18794 

18795 

18796 

18797 

18798 

18799 

18800 
18801 

18802 

18803 

18804 

18805 

18806 

18807 

18808 

18809 

18810 

18811 

18812 

18813 

18814 

18815 

18816 

18817 

18818 

18819 

18820 


NAME 

fold — filter for folding lines 

SYNOPSIS 

fold [—bs][—w width ] [file ...] 

DESCRIPTION 

Th e fold utility is a filter that shall fold lines from its input files, breaking the lines to have a 
maximum of width column positions (or bytes, if the -b option is specified). Lines shall be 
broken by the insertion of a <newline> character such that each output line (referred to later in 
this section as a segment) is the maximum width possible that does not exceed the specified 
number of column positions (or bytes). A line shall not be broken in the middle of a character. 
The behavior is undefined if width is less than the number of columns any single character in the 
input would occupy. 

If the <carriage-return>, <backspace>, or <tab> characters are encountered in the input, and the 
-b option is not specified, they shall be treated specially: 

<backspace> The current count of line width shall be decremented by one, although the count 
never shall become negative. The fold utility shall not insert a <newline> character 
immediately before or after any <backspace> character. 

<carriage-return> 

The current count of line width shall be set to zero. The fold utility shall not insert a 
<newline> character immediately before or after any <carriage-return> character. 

<tab> Each <tab> character encountered shall advance the column position pointer to the 

next tab stop. Tab stops shall be at each column position n such that n modulo 8 
equals 1. 

OPTIONS 

The fold utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-b Count width in bytes rather than column positions. 

-s If a segment of a line contains a <blank> character within the first zvidth column 

positions (or bytes), break the line after the last such <blank> character meeting the 
width constraints. If there is no <blank> character meeting the requirements, the -s 
option shall have no effect for that output segment of the input line. 

-w width Specify the maximum line length, in column positions (or bytes if -b is specified). 

The results are unspecified if zvidth is not a positive decimal number. The default 
value shall be 80. 

OPERANDS 

The following operand shall be supported: 

file A path name of a text file to be folded. If no file operands are specified, the 

standard input shall be used. 

STDIN 

The standard input shall be used only if no file operands are specified. See the INPUT FILES 
section. 
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18821 INPUT FILES 

18822 If the -b option is specified, the input files shall be text files except that the lines are not limited I 

18823 to |LINE_MAX} bytes in length. If the -b option is not specified, the input files shall be text files. I 


18824 ENVIRONMENT VARIABLES 

18825 The following environment variables shall affect the execution of fold: 


18826 

18827 

18828 

18829 

18830 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


18831 LC_ALL If set to a non-empty string value, override the values of all the other 

18832 internationalization variables. 


18833 

18834 

18835 

18836 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), and for the determination of the width in column 
positions each character would occupy on a constant-width font output device. 


18837 LC_MESSAGES 

18838 Determine the locale that should be used to affect the format and contents of 

18839 diagnostic messages written to standard error. 

18840 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


18841 ASYNCHRONOUS EVENTS 

18842 Default. 


18843 STDOUT 

18844 The standard output shall be a file containing a sequence of characters whose order shall be 

18845 preserved from the input files, possibly with inserted <newline> characters. 

18846 STDERR 

18847 Used only for diagnostic messages. 

18848 OUTPUT FILES 

18849 None. 


18850 EXTENDED DESCRIPTION 

18851 None. 


18852 EXIT STATUS 

18853 The following exit values shall be returned: 

18854 0 All input files were processed successfully. 

18855 >0 An error occurred. 


18856 CONSEQUENCES OF ERRORS 

18857 Default. 
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18858 APPLICATION USAGE 

18859 The cut and fold utilities can be used to create text files out of files with arbitrary line lengths. The 

18860 c»f utility should be used when the number of lines (or records) needs to remain constant. The 

18861 fold utility should be used when the contents of long lines need to be kept contiguous. 

18862 The fold utility is frequently used to send text files to printers that truncate, rather than fold, lines 

18863 wider than the printer is able to print (usually 80 or 132 column positions). 

18864 EXAMPLES 

18865 An example invocation that submits a file of possibly long lines to the printer (under the 

18866 assumption that the user knows the line width of the printer to be assigned by Ip): 

18867 fold — w 132 bigfile I lp 

18868 RATIONALE 

18869 Although terminal input in canonical processing mode requires the erase character (frequently 

18870 set to <backspace>) to erase the previous character (not byte or column position), terminal 

18871 output is not buffered and is extremely difficult, if not impossible, to parse correctly; the 

18872 interpretation depends entirely on the physical device that actually displays/prints/stores the 

18873 output. In all known internationalized implementations, the utilities producing output for mixed 

18874 column-width output assume that a <backspace> backs up one column position and outputs 

18875 enough <backspace>s to return to the start of the character when <backspace> is used to 

18876 provide local line motions to support underlining and emboldening operations. Since fold 

18877 without the -b option is dealing with these same constraints, <backspace> is always treated as 

18878 backing up one column position rather than backing up one character. 

18879 Historical versions of the fold utility assumed 1 byte was one character and occupied one column 

18880 position when written out. This is no longer always true. Since the most common usage of fold is 

18881 believed to be folding long lines for output to limited-length output devices, this capability was 

18882 preserved as the default case. The -b option was added so that applications could fold files with 

18883 arbitrary length lines into text files that could then be processed by the standard utilities. Note 

18884 that although the width for the -b option is in bytes, a line is never split in the middle of a 

18885 character. (It is unspecified what happens if a width is specified that is too small to hold a single 

18886 character found in the input followed by a <newline>.) 

18887 The tab stops are hardcoded to be every eighth column to meet historical practice. No new 

18888 method of specifying other tab stops was invented. 

18889 FUTURE DIRECTIONS 

18890 None. 

18891 SEE ALSO 

18892 cut 

18893 CHANGE HISTORY 

18894 First released in Issue 4. 

18895 Issue 6 

18896 The normative text is reworded to avoid use of the term "must” for application requirements. 
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18897 NAME 

18898 fort77 — FORTRAN compiler (FORTRAN) 

18899 SYNOPSIS 

18900 fd fort77 [—c] [—g] [-L directory ] . . . [—0 optlevel] [—o outfile ] [—s] [-w] 

18901 operand. . . 

18902 


18903 DESCRIPTION 

18904 The fort77 utility is the interface to the FORTRAN compilation system; it shall accept the full 

18905 FORTRAN-77 language defined by the ANSI X3.9-1978 standard. The system conceptually 

18906 consists of a compiler and link editor. The files referenced by operands are compiled and linked 

18907 to produce an executable file. It is unspecified whether the linking occurs entirely within the 

18908 operation of fort77; some systems may produce objects that are not fully resolved until the file is 

18909 executed. 


18910 If the -c option is present, for all path name operands of the form/z7e.f, the files: 

18911 $ (basename pathname, f) .o 

18912 shall be created or overwritten as the result of successful compilation. If the -c option is not 

18913 specified, it is unspecified whether such .o files are created or deleted for the file.f operands. 

18914 If there are no options that prevent link editing (such as -c) and all operands compile and link 

18915 without error, the resulting executable file shall be written into the file named by the -o option 

18916 (if present) or to the file a.out. The executable file shall be created as specified in the System 

18917 Interfaces volume of IEEE Std. 1003.1-200x, except that the file permissions shall be set to: 

18918 S_IRWXO I SJRWXG I S_IRWXU 

18919 and that the bits specified by the umask of the process shall be cleared. 


18920 OPTIONS 

18921 The fort77 utility shall conform to the System Interface Definitions volume of I 

18922 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that: I 

18923 • The -1 library operands have the format of options, but their position within a list of 

18924 operands affects the order in which libraries are searched. 

18925 • The order of specifying the multiple -L options is significant. 

18926 • Portable applications shall specify each option separately; that is, grouping option letters (for I 

18927 example, -eg) need not be recognized by all implementations. 

18928 The following options shall be supported: 


18929 -c Suppress the link-edit phase of the compilation, and do not remove any object files 

18930 that are produced. 


18931 -g 

18932 

18933 


Produce symbolic information in the object or executable files; the nature of this 
information is unspecified, and may be modified by implementation-dependent 
interactions with other options. 


18934 -S 

18935 

18936 

18937 

18938 


Produce object or executable files, or both, from which symbolic and other 
information not required for proper execution using the exec family of functions 
defined in the System Interfaces volume of IEEE Std. 1003.1-200x has been 
removed (stripped). If both -g and -s options are present, the action taken is 
unspecified. 


18939 -o outfile Use the path name outfile, instead of the default a.out, for the executable file 

18940 produced. If the -o option is present with -c, the result is unspecified. 
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18941 

18942 

18943 

18944 

18945 

18946 

18947 

18948 

18949 

18950 

18951 

18952 

18953 

18954 

18955 

18956 

18957 

18958 

18959 

18960 

18961 

18962 

18963 

18964 

18965 

18966 

18967 

18968 

18969 

18970 

18971 

18972 

18973 

18974 

18975 

18976 

18977 

18978 

18979 

18980 

18981 

18982 


-L directory Change the algorithm of searching for the libraries named in -1 operands to look in 
the directory named by the directory path name before looking in the usual places. 
Directories named in -L options shall be searched in the specified order. At least 
ten instances of this option shall be supported in a single fort77 command 
invocation. If a directory specified by a -L option contains a file named libf.a, the 
results are unspecified. 

-O optlevel Specify the level of code optimization. If the optlevel option-argument is the digit 
'O', all special code optimizations shall be disabled. If it is the digit ' 1', the 
nature of the optimization is unspecified. If the -O option is omitted, the nature of 
the system's default optimization is unspecified. It is unspecified whether code 
generated in the presence of the -O 0 option is the same as that generated when 
-O is omitted. Other optlevel values may be supported. 


-w 


Suppress warnings. 


Multiple instances of -L options can be specified. 


OPERANDS 

An operand is either in the form of a path name or the form -1 library. At least one operand of the 
path name form shall be specified. The following operands shall be supported: 

file, f The path name of a FORTRAN source file to be compiled and optionally passed to 

the link editor. The file name operand shall be of this form if the -c option is used. 

file, a A library of object files typically produced by ar, and passed directly to the link 

editor. Implementations may recognize implementation-dependent suffixes other 
than .a as denoting object file libraries. 

file, o An object file produced by fort77 -c and passed directly to the link editor. 

Implementations may recognize implementation-dependent suffixes other than .o 
as denoting object files. 

The processing of other files is implementation-dependent. 

-1 library (The letter ell.) Search the library named: 

lib library .a 

A library is searched when its name is encountered, so the placement of a -1 
operand is significant. Several standard libraries can be specified in this manner, as 
described in the EXTENDED DESCRIPTION section. Implementations may 
recognize implementation-dependent suffixes other than .a as denoting libraries. 

STDIN 

Not used. 


INPUT FILES 

The input file shall be one of the following: a text file containing FORTRAN source code; an 
object file in the format produced by fort77 -c; or a library of object files, in the format produced 
by archiving zero or more object files, using ar. Implementations may supply additional utilities 
that produce files in these formats. Additional input files are implementation-dependent. 

A <tab> character encountered within the first six characters on a line of source code shall cause 
the compiler to interpret the following character as if it were the seventh character on the line 
(that is, in column 7). 
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18983 ENVIRONMENT VARIABLES 

18984 The following environment variables shall affect the execution of fort77: 


18985 

18986 

18987 

18988 

18989 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


18990 LC_ALL If set to a non-empty string value, override the values of all the other 

18991 internationalization variables. 


18992 

18993 

18994 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


18995 LC_MESSAGES 

18996 Determine the locale that should be used to affect the format and contents of 

18997 diagnostic messages written to standard error. 

18998 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

18999 TMPDIR Determine the path name that should override the default directory for temporary 

19000 files, if any. 


19001 ASYNCHRONOUS EVENTS 

19002 Default. 


19003 STDOUT 

19004 Not used. 


19005 STDERR 

19006 Used only for diagnostic messages. If more than one file operand ending in .f (or possibly other 

19007 unspecified suffixes) is given, for each such file: 

19008 "%s:\n", <file> 

19009 may be written to allow identification of the diagnostic message with the appropriate input file. 

19010 This utility may produce warning messages about certain conditions that do not warrant 

19011 returning an error (non-zero) exit value. 

19012 OUTPUT FILES 

19013 Object files, listing files and executable files shall be produced in unspecified formats. 

19014 EXTENDED DESCRIPTION 


19015 Standard Libraries 

19016 The fort77 utility shall recognize the following -1 operand for the standard library: 

19017 -1 f This library contains all library functions referenced in the ANSI X3.9-1978 

19018 standard. This operand shall not be required to be present to cause a search of this 

19019 library. 

19020 In the absence of options that inhibit invocation of the link editor, such as -c, the fort77 utility 

19021 shall cause the equivalent of a -1 f operand to be passed to the link editor as the last -1 operand, 

19022 causing it to be searched after all other object files and libraries are loaded. 

19023 It is unspecified whether the library libf.a exists as a regular file. The implementation may 

19024 accept as -1 operands names of objects that do not exist as regular files. 
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19025 External Symbols 

19026 The FORTRAN compiler and link editor shall support the significance of external symbols up to 

19027 a length of at least 31 bytes; case folding is permitted. The action taken upon encountering 

19028 symbols exceeding the implementation-dependent maximum symbol length is unspecified. 

19029 The compiler and link editor shall support a minimum of 511 external symbols per source or 

19030 object file, and a minimum of 4095 external symbols total. A diagnostic message is written to 

19031 standard output if the implementation-dependent limit is exceeded; other actions are 

19032 unspecified. 

19033 EXIT STATUS 

19034 The following exit values shall be returned: 

19035 0 Successful compilation or link edit. 

19036 >0 An error occurred. 

19037 CONSEQUENCES OF ERRORS 

19038 When fort77 encounters a compilation error, it shall write a diagnostic to standard error and 

19039 continue to compile other source code operands. It shall return a non-zero exit status, but it is 

19040 implementation-dependent whether an object module is created. If the link edit is unsuccessful, 

19041 a diagnostic message shall be written to standard error, and fort77 shall exit with a non-zero 

19042 status. 

19043 APPLICATION USAGE 

19044 None. 

19045 EXAMPLES 

19046 The following usage example compiles xyz.f and creates the executable file too: 

19047 fort77 — o foo xyz.f 

19048 The following example compiles xyz.f and creates the object file xyz.o: 

19049 fort77 —c xyz.f 

19050 The following example compiles xyz.f and creates the executable file a.out: 

19051 fort77 xyz.f 

19052 The following example compiles xyz.f, links it with b.o, and creates the executable a.out: 

19053 fort77 xyz.f b.o 

19054 RATIONALE 

19055 The name of this utility was chosen as fort77 to parallel the renaming of the C compiler. The 

19056 name f77 was not chosen to avoid problems with historical implementations. The 

19057 ANSI X3.9-1978 standard was selected as a normative reference because the ISO/IEC version of I 

19058 FORTRAN-77 has been superseded by the ISO/IEC 1539:1990 standard (Fortran-90). I 

19059 The file inclusion and symbol definition #define mechanisms used by the c89 utility were not 

19060 included in this volume of IEEE Std. 1003.1-200x—even though they are commonly 

19061 implemented—since there is no requirement that the FORTRAN compiler use the C 

19062 preprocessor. 

19063 The -onetrip option was not included in this volume of IEEE Std. 1003.1-200x, even though 

19064 many historical compilers support it, because it is derived from FORTRAN-66; it is an 

19065 anachronism that should not be perpetuated. 

19066 Some implementations produce compilation listings. This aspect of FORTRAN has been left 

19067 unspecified because there was controversy concerning the various methods proposed for 
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19068 

19069 

19070 

19071 

19072 
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19074 
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19114 


implementing it: a -V option overlapped with historical vendor practice and a naming 
convention of creating files with .1 suffixes collided with historical lex file naming practice. 

There is no -I option in this version of this volume of IEEE Std. 1003.1-200x to specify a directory 
for file inclusion. An INCLUDE directive has been a part of the Fortran-90 discussions, but an 
interface supporting that standard is not in the current scope. 

It is noted that many FORTRAN compilers produce an object module even when compilation 
errors occur; during a subsequent compilation, the compiler may patch the object module rather 
than recompiling all the code. Consequently, it is left to the implementor whether or not an 
object file is created. 

A reference to MIL-STD-1753 was removed from an early proposal in response to a request from 
the POSIX FORTRAN-binding standard developers. It was not the intention of the standard 
developers to require certification of the FORTRAN compiler, and the POSIX.9 standard does 
not specify the military standard or any special preprocessing requirements. Furthermore, use of 
that document would have been inappropriate for an international standard. 

The specification of optimization has been subject to changes through early proposals. At one 
time, -O and -N were Booleans: optimize and do not optimize (with an unspecified default). 
Some historical practice lead this to be changed to: 

-O 0 No optimization. 

-O 1 Some level of optimization. 

-O n Other, unspecified levels of optimization. 

It is not always clear whether "good code generation" is the same thing as optimization. Simple 
optimizations of local actions do not usually affect the semantics of a program. The -O 0 option 
has been included to accommodate the very particular nature of scientific calculations in a 
highly optimized environment; compilers make errors. Some degree of optimization is expected, 
even if it is not documented here, and the ability to shut it off completely could be important 
when porting an application. An implementation may treat -O 0 as "do less than normal" if it 
wishes, but this is only meaningful if any of the operations it performs can affect the semantics 
of a program. It is highly dependent on the implementation whether doing less than normal is 
logical. It is not the intent of the -O 0 option to ask for inefficient code generation, but rather to 
assure that any semantically visible optimization is suppressed. 

The specification of standard library access is consistent with the C compiler specification. 
Implementations are not required to have /usr/lib/libf.a, as many historical implementations do, 
but if not they are required to recognize f as a token. 

External symbol size limits are in normative text; portable applications need to know these 
limits. However, the minimum maximum symbol length should be taken as a constraint on a 
portable application, not on an implementation, and consequently the action taken for a symbol 
exceeding the limit is unspecified. The minimum size for the external symbol table was added 
for similar reasons. 

The CONSEQUENCES OF ERRORS section clearly specifies the behavior of the compiler when 
compilation or link-edit errors occur. The behavior of several historical implementations was 
examined, and the choice was made to be silent on the status of the executable, or a.out, file in 
the face of compiler or linker errors. If a linker writes the executable file, then links it on disk 
with lseek( )s and ivrite{ )s, the partially linked executable file can be left on disk and its execute 
bits turned off if the link edit fails. However, if the linker links the image in memory before 
writing the file to disk, it need not touch the executable file (if it already exists) because the link 
edit fails. Since both approaches are historical practice, a portable application shall rely on the 
exit status otfort77, rather than on the existence or mode of the executable file. 
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19115 The -g and -s options are not specified as mutually-exclusive. Historically these two options 

19116 have been mutually-exclusive, but because both are so loosely specified, it seemed appropriate 

19117 to leave their interaction unspecified. 

19118 The requirement that portable applications specify compiler options separately is to reserve the 

19119 multi-character option namespace for vendor-specific compiler options, which are known to 

19120 exist in many historical implementations. Implementations are not required to recognize, for 

19121 example, -gc as if it were -g -c; nor are they forbidden from doing so. The SYNOPSIS shows all 

19122 of the options separately to highlight this requirement on applications. 

19123 Echoing file names to standard error is considered a diagnostic message because it would 

19124 otherwise be difficult to associate an error message with the erring file. They are described with 

19125 "may" to allow implementations to use other methods of identifying files and to parallel the 

19126 description in c89. 

19127 FUTURE DIRECTIONS 

19128 A compilation system based on the ISO/IEC 1539:1990 standard (Fortran-90) shall be considered I 

19129 for a future issue; it may have a different utility name from fort77. I 

19130 SEE ALSO 

19131 ar , asa , c89 , umask 

19132 CHANGE HISTORY 

19133 First released in Issue 4. 

19134 Issue 6 

19135 This utility is now marked as part of the FORTRAN Development Utilities option. I 

19136 The normative text is reworded to avoid use of the term "must" for application requirements. I 
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NAME 

fuser — list process IDs of all processes that have one or more files open 

SYNOPSIS 

xsi fuser [ —cfu ] file . . . 


DESCRIPTION 

The fuser utility shall write to standard output the process IDs of processes running on the local 
system that have one or more named files open. For block special devices, all processes using 
any file on that device are listed. 

The fuser utility shall write to standard error additional information about the named files 
indicating how the file is being used. 

Any output for processes running on remote systems that have a named file open is unspecified. 

A user may need appropriate privilege to invoke th e fuser utility. 

OPTIONS 

The fuser utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-c The file is treated as a mount point and the utility shall report on any files open in 

the file system. 

-f The report shall be only for the named files. 

-u The user name, in parentheses, associated with each process ID written to standard 

output shall be written to standard error. 

OPERANDS 

The following operand shall be supported: 

file A path name on which the file or file system is to be reported. 

STDIN 

Not used. 

INPUT FILES 

The user database. 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of fuser: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contain an invalid setting, the utility behaves as if none of the variables had been 
set. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
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19180 diagnostic messages written to standard error. 

19181 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

19182 ASYNCHRONOUS EVENTS 

19183 Default. 

19184 STDOUT 

19185 Th e fuser utility shall write the process ID for each process using each file given as an operand to 

19186 standard output in the following format: 

19187 "%d", <process_id> 

19188 STDERR 

19189 Th efuser utility shall write diagnostic messages to standard error. 

19190 Th e fuser utility also shall write the following to standard error: 

19191 • The path name of each named file is written followed immediately by a colon. 

19192 • For each process ID written to standard output, the character ' c' shall be written to 

19193 standard error if the process is using the file as its current directory and the character ' r' 

19194 shall be written to standard error if the process is using the file as its root directory. 

19195 Implementations may write other alphabetic characters to indicate other uses of files. 

19196 • When the -u option is specified, characters indicating the use of the file shall be followed 

19197 immediately by the user name, in parentheses, corresponding to the process' real user ID. If 

19198 the user name cannot be resolved from the process' real user ID, the process' real user ID 

19199 shall be written instead of the user name. 

19200 When standard output and standard error are directed to the same file, the output shall be 

19201 interspersed so that the file name appears at the start of each line, followed by the process ID 

19202 and characters indicating the use of the file. Then, if the -u option is specified, the user name or 

19203 user ID for each process using that file shall be written. 

19204 A <newline> character shall be written to standard error after the last output described above 

19205 for each file operand. 

19206 OUTPUT FILES 

19207 None. 

19208 EXTENDED DESCRIPTION 

19209 None. 

19210 EXIT STATUS 

19211 The following exit values shall be returned: 

19212 0 Successful completion. 

19213 >0 An error occurred. 

19214 CONSEQUENCES OF ERRORS 

19215 Default. 
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19216 APPLICATION USAGE 

19217 None. 

19218 EXAMPLES 

19219 The command: 

19220 fuser -fu . 

19221 writes to standard output the process IDs of processes that are using the current directory and 

19222 writes to standard error an indication of how those processes are using the directory and the 

19223 user names associated with the processes that are using the current directory. 

19224 RATIONALE 

19225 None. 

19226 FUTURE DIRECTIONS 

19227 None. 

19228 SEE ALSO 

19229 None. 

19230 CHANGE HISTORY 

19231 First released in Issue 5. 
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19232 NAME 

19233 gencat — generate a formatted message catalog 

19234 SYNOPSIS 

19235 xsi gencat cat file msgfile. . . 

19236 

19237 DESCRIPTION 

19238 The gencat utility shall merge the message text source files msgfile into a formatted message 

19239 catalog catfile . The file catfile shall be created if it does not already exist. If catfile does exist, its 

19240 messages shall be included in the new catfile. If set and message numbers collide, the new 

19241 message text defined in msgfile shall replace the old message text currently contained in catfile. 

19242 OPTIONS 

19243 None. 


19244 OPERANDS 

19245 The following operands shall be supported: 


19246 

19247 


catfile A path name of the formatted message catalog. If ' - ' is specified, standard output 

shall be used. The format of the message catalog produced is unspecified. 


19248 

19249 

19250 


msgfile A path name of a message text source file. If is specified for an instance of 

msgfile, standard input shall be used. The format of message text source files is 
defined in the EXTENDED DESCRIPTION section. 


19251 STDIN 

19252 The standard input shall not be used unless a msgfile operand is specified as ' . 


19253 INPUT FILES 

19254 The input files shall be text files. 


19255 ENVIRONMENT VARIABLES 

19256 The following environment variables shall affect the execution of gencat: 


19257 

19258 

19259 

19260 

19261 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


19262 LC_ALL If set to a non-empty string value, override the values of all the other 

19263 internationalization variables. 


19264 

19265 

19266 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


19267 

19268 

19269 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


19270 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


19271 ASYNCHRONOUS EVENTS 

19272 Default. 
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19273 STDOUT 

19274 The standard output shall not be used unless the catfile operand is specified as ' - '. 

19275 STDERR 

19276 Used only for diagnostic messages. 

19277 OUTPUT FILES 

19278 None. 


19279 EXTENDED DESCRIPTION 

19280 The application shall ensure that the format of a message text source file is defined as follows. I 

19281 Note that the fields of a message text source line are separated by a single <blank> character. I 

19282 Any other <blank> characters are considered as being part of the subsequent field. 


19283 

19284 

19285 

19286 

19287 

19288 

19289 

19290 

19291 

19292 

19293 


$set n comment 

This line specifies the set identifier of the following messages until the next $set or 
end-of-file appears. The n denotes the set identifier, which is defined as a number 
in the range [1, |NL_SETMAX}] (see the <limits.h> header defined in the System 
Interfaces volume of IEEE Std. 1003.1-200x). The application shall ensure that set 
identifiers are presented in ascending order within a single source file, but need 
not be contiguous. Any string following the set identifier shall be treated as a 
comment. If no $set directive is specified in a message text source file, all messages 
shall be located in an implementation-dependent default message set NL_SETD 
(see the <nl_types.h> header defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x). 


19294 $delset n comment 

19295 This line deletes message set n from an existing message catalog. The n denotes the 

19296 set number [1, |NL_SETMAX}]. Any string following the set number shall be 

19297 treated as a comment. 


19298 $ comment A line beginning with ' $' followed by a <blank> character shall be treated as a 

19299 comment. 


19300 

19301 

19302 

19303 

19304 

19305 

19306 

19307 

19308 

19309 

19310 

19311 

19312 


m message-text 

The m denotes the message identifier, which is defined as a number in the range [1, 
|NL_MSGMAX}] (see the <limits.h> defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x). The message-text shall be stored in the message catalog with 
the set identifier specified by the last $set directive, and with message identifier m. 

If the message-text is empty, and a <blank> character field separator is present, an 
empty string shall be stored in the message catalog. If a message source line has a 
message number, but neither a field separator nor message-text , the existing 
message with that number (if any) shall be deleted from the catalog. The I 
application shall ensure that message identifiers are in ascending order within a I 
single set, but need not be contiguous. The application shall ensure that the length I 
of message-text is in the range [0, |NL_TEXTMAX}] (see the <limits.h> header I 
defined in the System Interfaces volume of IEEE Std. 1003.1-200x). 


19313 $quote n This line specifies an optional quote character c, which can be used to surround 

19314 message-text so that trailing spaces or null (empty) messages are visible in a 

19315 message source line. By default, or if an empty $quote directive is supplied, no 

19316 quoting of message-text shall be recognized. 


19317 Empty lines in a message text source file shall be ignored. The effects of lines starting with any 

19318 character other than those defined above are implementation-dependent. 
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19319 Text strings can contain the special characters and escape sequences defined in the following 

19320 table: 

19321 


19322 

Description 

Symbol 

Sequence 

19323 

<newline> 

NL(LF) 

\n 

19324 

Horizontal tab 

HT 

\t 

19325 

<vertical-tab> 

VT 

\ v 

19326 

<backspace> 

BS 

\b 

19327 

<carriage-return> 

CR 

\r 

19328 

<form-feed> 

FF 

\f 

19329 

Backslash 

\ 

w 

19330 

Bit pattern 

ddd 

\ddd 


19331 The escape sequence "\ddd" consists of backslash followed by one, two, or three octal digits, 

19332 which shall be taken to specify the value of the desired character. If the character following a 

19333 backslash is not one of those specified, the backslash shall be ignored. 

19334 Backslash (' \') followed by a <newline> character is also used to continue a string on the 

19335 following line. Thus, the following two lines describe a single message string: 

19336 1 This line continues \ 

19337 to the next line 

19338 which is equivalent to: 

19339 1 This line continues to the next line 

19340 EXIT STATUS 

19341 The following exit values shall be returned: 

19342 0 Successful completion. 

19343 >0 An error occurred. 

19344 CONSEQUENCES OF ERRORS 

19345 Default. 

19346 APPLICATION USAGE 

19347 Message catalogs produced by gencat are binary encoded, meaning that their portability cannot 

19348 be guaranteed between different types of machine. Thus, just as C programs need to be 

19349 recompiled for each type of machine, so message catalogs must be recreated via gencat. 

19350 EXAMPLES 

19351 None. 

19352 RATIONALE 

19353 None. 

19354 FUTURE DIRECTIONS 

19355 None. 

19356 SEE ALSO 

19357 iconv, the System Interfaces volume of IEEE Std. 1003.1-200x, <limits.h> 

19358 CHANGE HISTORY 

19359 First released in Issue 3. 
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19360 

19361 

19362 

19363 

19364 


Issue 4 

Format reorganized. 

Internationalized environment variable support mandated. 

Issue 6 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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19365 NAME 

19366 get — get a version of an SCCS file (DEVELOPMENT) 

19367 SYNOPSIS 

19368 xsi get [-begkmlLpst] [—c cutoff ] [—i list ] [—r SID ] [—x list ] file. . . 

19369 

19370 DESCRIPTION 

19371 The get utility shall generate a text file from each named SCCS file according to the specifications 

19372 given by its options. 


19373 

19374 


The generated text is normally written into a file called the g-file whose name is derived from 
the SCCS file name by simply removing the leading s.. 


19375 OPTIONS 

19376 

19377 


19378 

19379 

19380 

19381 

19382 

19383 

19384 

19385 

19386 

19387 

19388 

19389 

19390 

19391 

19392 

19393 

19394 

19395 

19396 

19397 

19398 

19399 

19400 

19401 

19402 

19403 

19404 

19405 

19406 

19407 

19408 


The yet utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported: 

-r SID Indicate the SCCS Identification String (SID) of the version (delta) of an SCCS file 

to be retrieved. The table shows, for the most useful cases, what version of an 
SCCS file is retrieved (as well as the SID of the version to be eventually created by 
delta if the -e option is also used), as a function of the SID specified. 

-c cutoff Indicate the cutoff date-time, in the form: 

YY[MM[DD[HH[MM[SS ]]]]] 

For the YY component, values in the range [69-99] shall refer to years in the 
twentieth century (1969 to 1999 inclusive); values in the range [00-68] shall refer to 
years in the twenty-first century (2000 to 2068 inclusive). 

No changes (deltas) to the SCCS file that were created after the specified cutoff 
date-time are included in the generated text file. Units omitted from the date-time 
default to their maximum possible values; for example, -c 7502 is equivalent to -c 
750228235959. 

Any number of non-numeric characters may separate the various 2-digit pieces of 
the cutoff date-time. This feature allows the user to specify a cutoff date in the form: 
-c ”77/2/2 9:22:25". 

-e Indicate that the get is for the purpose of editing or making a change (delta) to the 

SCCS file via a subsequent use of delta. The -e option used in a get for a particular 
version (SID) of the SCCS file prevents further get commands from editing on the 
same SID until delta is executed or the j (joint edit) flag is set in the SCCS file. 
Concurrent use of get -e for different SIDs is always allowed. 

If the g-file generated by get with a -e option is accidentally ruined in the process 
of editing, it may be regenerated by re-executing the get command with the -k 
option in place of the -e option. 

SCCS file protection specified via the ceiling, floor, and authorized user list stored 
in the SCCS file is enforced when the -e option is used. 

-b Use with the -e option to indicate that the new delta should have an SID in a new 

branch as shown in the table below. This option is ignored if the b flag is not 
present in the file or if the retrieved delta is not a leaf delta. (A leaf delta is one that 
has no successors on the SCCS file tree.) 
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19409 


Note: A branch delta may always be created from a non-leaf delta. 

19410 

19411 

-i list 

Indicate a list of deltas to be included (forced to be applied) in the creation of the 
generated file. The list has the following syntax: 

19412 

19413 


<list> ::= <range> | <list> , <range> 

<range> ::= SID | SID — SID 

19414 

19415 

19416 


SID, the SCCS Identification of a delta, may be in any form shown in the "SID 
Specified" column of the table in the EXTENDED DESCRIPTION section. Partial 
SIDs are interpreted as shown in the "SID Retrieved" column of the table. 

19417 

19418 

-x list 

Indicate a list of deltas to be excluded (forced not to be applied) in the creation of 
the generated file. See the -i option for the list format. 

19419 

19420 

-k 

Suppress replacement of identification keywords (see below) in the retrieved text 
by their value. The -k option is implied by the -e option. 

19421 

-1 

Write a delta summary into an 1-file. 

19422 

19423 

19424 

-L 

Write a delta summary to standard output. All informative output that normally is 
written to standard output is written to standard error instead, unless the -s 
option is used, in which case it is suppressed. 

19425 

19426 

19427 

-P 

Write the text retrieved from the SCCS file to the standard output. No g-file is 
created. All informative output that normally goes to the standard output goes to 
standard error instead, unless the -s option is used, in which case it disappears. 

19428 

19429 

19430 

-s 

Suppress all informative output normally written to standard output. However, 
fatal error messages (which are always written to the standard error) remain 
unaffected. 

19431 

19432 

-m 

Precede each text line retrieved from the SCCS file by the SID of the delta that 
inserted the text line in the SCCS file. The format is: 

19433 


"%s\ts", <SID>, <text line> 

19434 

19435 

-n 

Precede each generated text line with the %M% identification keyword value (see 
below). The format is: 

19436 


"%s\ts", <%M% value>, <text line> 

19437 

19438 


When both the -m and -n options are used, the <text lino is replaced by the -m 
option-generated format. 

19439 

19440 

-g 

Suppress the actual retrieval of text from the SCCS file. It is primarily used to 
generate an 1-file, or to verify the existence of a particular SID. 

19441 

19442 

-t 

Use to access the most recently created (top) delta in a given release (for example, 
-r 1), or release and level (for example, -r 1.2). 

19443 OPERANDS 

19444 The following operands shall be supported: 

19445 

19446 

19447 

19448 

file 

A path name of an existing SCCS file or a directory. If file is a directory, get behaves 
as though each file in the directory were specified as a named file, except that 
non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. 

19449 

19450 

19451 


If a single instance file is specified as ' , the standard input is read; each line of 

the standard input is taken to be the name of an SCCS file to be processed. Non- 
SCCS files and unreadable files are silently ignored. 
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19452 STDIN 

19453 The standard input is a text file used only if the file operand is specified as ' . Each line of the 

19454 text file is interpreted as an SCCS path name. 

19455 INPUT FILES 

19456 The SCCS files are files of an unspecified format. 


19457 ENVIRONMENT VARIABLES 

19458 The following environment variables shall affect the execution of get: 


19459 

19460 

19461 

19462 

19463 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


19464 

19465 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


19466 

19467 

19468 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


19469 LC_MESSAGES 

19470 Determine the locale that should be used to affect the format and contents of 

19471 diagnostic messages written to standard error, and informative messages written 

19472 to standard output (or standard error, if the -p option is used). 


19473 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


19474 ASYNCHRONOUS EVENTS 

19475 Default. 


19476 STDOUT 

19477 For each file processed, get shall write to standard output the SID being accessed and the number 

19478 of lines retrieved from the SCCS file, in the following format: 

19479 "%s\n%d lines\n", <SID>, <number of lines> 

19480 If the -e option is used, the SID of the delta to be made shall appear after the SID accessed and 

19481 before the number of lines generated, in the POSIX locale: 

19482 "%s\nnew delta %s\n%d\n", <SID accessed>, <SID to be made>, 

19483 <number of lines> 

19484 If there is more than one named file or if a directory or standard input is named, each path name 

19485 shall be written before each of the lines shown in one of the preceding formats: 

19486 "\n%s:\n", <pathname> 

19487 If the -L option is used, a delta summary shall be written following the format specified below 

19488 for 1-files. 

19489 If the -i option is used, included deltas are listed following the notation, in the POSIX locale: 

19490 "Included:\n" 

19491 If the -x option is used, excluded deltas are listed following the notation, in the POSIX locale: 

19492 "Excluded:\n" 
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19493 

19494 

19495 

19496 

19497 

19498 

19499 

19500 

19501 

19502 

19503 

19504 

19505 

19506 

19507 

19508 

19509 

19510 

19511 

19512 

19513 

19514 

19515 

19516 

19517 

19518 

19519 

19520 

19521 

19522 

19523 

19524 

19525 

19526 

19527 

19528 

19529 

19530 

19531 

19532 

19533 

19534 


If the -p or -L options are specified, the standard output consists of the text retrieved from the 
SCCS file. 

STDERR 

The standard error shall be used only for diagnostic messages, except if the -p or -L options are 
specified, it includes all informative messages normally sent to standard output. 

OUTPUT FILES 

Several auxiliary files may be created by get. These files are known generically as the g-file, 1- 
file, p-file, and z-file. The letter before the hyphen is called the tag. An auxiliary file name is I 
formed from the SCCS file name: the application shall ensure that the last component of all I 
SCCS file names is of the form s .module-name; the auxiliary files are named by replacing the I 
leading s with the tag. The g-file is an exception to this scheme: the g-file is named by removing 
the s. prefix. For example, for s.xyz.c, the auxiliary file names would be xyz.c, l.xyz.c, p.xyz.c, 
and z.xyz.c, respectively. 

The g-file, which contains the generated text, is created in the current directory (unless the -p 
option is used). A g-file is created in all cases, whether or not any lines of text were generated by 
the get. It is owned by the real user. If the -k option is used or implied, it is writable by the 
owner only (read-only for everyone else); otherwise, it is read-only. Only the real user need have 
write permission in the current directory. 

The 1-file contains a table showing which deltas were applied in generating the retrieved text. 
The 1-file is created in the current directory if the -1 option is used; it is read-only and it is 
owned by the real user. Only the real user need have write permission in the current directory. 

Lines in the 1-file have the following format: 

"%c%c%cA%s\t%sA%s\n", <codel>, <code2>, <code3>, 

<SID>, <date-time>, <login> 

where the entries are: 


<codel> 

<code2> 

<code3> 


A <space> character if the delta was applied;' *' otherwise. 

A <space> character if the delta was applied or was not applied and ignored; ' 
if the delta was not applied and was not ignored. 


A character indicating a special reason why the delta was or was not applied: 

I Included. 

X Excluded. 

C Cut off (by a-c option). 

<date-time> Date and time (using the date utility's %y/%m/%d %T format) of creation. 

<login> Login name of person who created delta. 

The comments and MR data follow on subsequent lines, indented one <tab> character. A blank 
line terminates each entry. 


The p-file is used to pass information resulting from a get with a -e option along to delta. Its 
contents are also used to prevent a subsequent execution of get with a -e option for the same SID 
until delta is executed or the joint edit flag, j, is set in the SCCS file. The p-file is created in the I 
directory containing the SCCS file and the application shall ensure that the effective user has I 
write permission in that directory. It is writable by owner only, and it is owned by the effective I 
user. Each line in the p-file has the following format: I 
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19535 "%sA%sA%sA%sA%s7ts%s\n", <g-file SID>, <SID of new delta>, 

19536 <login-name of real user>, <date~time>, <i-value>, <x-value> 

19537 Notes to Reviewers 

19538 This section zvith side shading will not appear in the final copy. - Ed. 

19539 The example above has been fixed to include n. 

19540 where <i-value> is the value of the list option-argument to -i (or null) and <x-value> is the value 

19541 of the list option-argument to -x (or null). There can be an arbitrary number of lines in the p-file 

19542 at any time; no two lines can have the same new delta SID. 

19543 The z-file serves as a lock-out mechanism against simultaneous updates. Its contents are the 

19544 binary process ID of the command (that is, get) that created it. The z-file is created in the 

19545 directory containing the SCCS file for the duration of get. The same protection restrictions as 

19546 those for the p-file apply for the z-file. The z-file is created read-only. 

19547 EXTENDED DESCRIPTION 


19548 

Determination of SCCS Identification String 

19549 

SID* 

-b Keyletter 

Other 

SID 

SID of Delta 

19550 

Specified 

Usedt 

Conditions 

Retrieved 

to be Created 

19551 

none:): 

no 

R defaults to mR 

mR.mL 

mR.(mL-t-l) 

19552 

none:): 

yes 

R defaults to mR 

mR.mL 

mR.mL. (mB+l).l 

19553 

R 

no 

R > mR 

mR.mL 

^ *** 

19554 

R 

no 

R = mR 

mR.mL 

mR.(mL+l) 

19555 

R 

yes 

R > mR 

mR.mL 

mR.mL.(mB+l).l 

19556 

R 

yes 

R = mR 

mR.mL 

mR.mL. (mB+l).l 

19557 

R 

- 

R < mR and 

hR.mL** 

hR.mL.(mB+l).l 

19558 



R does not exist 



19559 

R 

- 

Trunk successor in release > R 

R.mL 

R.mL.(mB+l).l 

19560 



and R exists 



19561 

R.L 

no 

No trunk successor 

R.L 

R.(L+1) 

19562 

R.L 

yes 

No trunk successor 

R.L 

R.L.(mB+l).l 

19563 

R.L 

- 

Trunk successor 

R.L 

R.L.(mB+l).l 

19564 



in release > R 



19565 

R.L.B 

no 

No branch successor 

R.L.B.mS 

R.L.B.(mS+1) 

19566 

R.L.B 

yes 

No branch successor 

R.L.B.mS 

R.L.(mB+l).l 

19567 

R.L.B.S 

no 

No branch successor 

R.L.B.S 

R.L.B.(S+1) 

19568 

R.L.B.S 

yes 

No branch successor 

R.L.B.S 

R.L.(mB+l).l 

19569 

R.L.B.S 

- 

Branch successor 

R.L.B.S 

R.L.(mB+l).l 


19570 

19571 

19572 

19573 

19574 

19575 


R, L, B, and S are the release, level, branch, and sequence components of the SID, 
respectively; m means maximum. Thus, for example, R.mL means "the maximum level 
number within release R"; R.L.(mB+l).l means "the first sequence number on the new 
branch (that is, maximum branch number plus one) of level L within release R". Note 
that if the SID specified is of the form R.L, R.L.B, or R.L.B.S, each of the specified I 
components shall exist. I 


19576 


hR is the highest existing release that is lower than the specified, nonexistent, release R. 
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19577 

*** 

This is used to force creation of the first delta in a new release. 

19578 

19579 

+ 

The -b option is effective only if the b flag is present in the file. An entry of ' - ' means 
"irrelevant”. 

19580 

19581 

19582 

t 

This case applies if the d (default SID) flag is not present in the file. If the d flag is 
present in the file, then the SID obtained from the d flag is interpreted as if it had been 
specified on the command line. Thus, one of the other cases in this table applies. 

19583 

Identification Keywords 

19584 

19585 

19586 

Identifying information is inserted into the text retrieved from the SCCS file by replacing 
identification keywords with their value wherever they occur. The following keywords may be 
used in the text stored in an SCCS file: 

19587 

19588 

%M% 

Module name: either the value of the m flag in the file, or if absent, the name of the 
SCCS file with the leading s. removed. 

19589 

19590 

%I% 

SCCS identification (SID) (%R%.%L% or %R%.%L%.%B%.%S%) of the retrieved 
text. 

19591 

%R% 

Release. 

19592 

%L% 

Level. 

19593 

%B% 

Branch. 

19594 

%S% 

Sequence. 

19595 

%D% 

Current date (YY/MM/DD). 

19596 

%H% 

Current date (MM/DD/YY). 

19597 

%T% 

Current time (HH:MM:SS). 

19598 

%E% 

Date newest applied delta was created (YY/MM/DD). 

19599 

%G% 

Date newest applied delta was created (MM/DD/YY). 

19600 

%U% 

Time newest applied delta was created ( HH:MM:SS ). 

19601 

%Y% 

Module type: value of the t flag in the SCCS file. 

19602 

%F% 

SCCS file name. 

19603 

%P% 

SCCS absolute path name. 

19604 

%Q% 

The value of the q flag in the file. 

19605 

19606 

19607 

%C% 

Current line number. This keyword is intended for identifying messages output by 
the program, such as "this should not have happened" type errors. It is not 
intended to be used on every line to provide sequence numbers. 

19608 

%Z% 

The four-character string "@ (#) " recognizable by what. 

19609 

%W% 

A shorthand notation for constructing ivhat strings: 

19610 


% W %—% Z %%M%<t cLk)^* % I % 

19611 

%A% 

Another shorthand notation for constructing what strings: 

19612 


-O A-Q —-O Z 'o'o Y 'o'oM'o'o I -o "o Z "6 
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19613 EXIT STATUS 

19614 The following exit values shall be returned: 

19615 0 Successful completion. 

19616 >0 An error occurred. 

19617 CONSEQUENCES OF ERRORS 

19618 Default. 

19619 APPLICATION USAGE 

19620 None. 

19621 EXAMPLES 

19622 None. 

19623 RATIONALE 

19624 None. 

19625 FUTURE DIRECTIONS 

19626 The -lp option may be withdrawn in a future issue. 

19627 SEE ALSO 

19628 admin , delta, prs, what 

19629 CHANGE HISTORY 

19630 First released in Issue 2. 

19631 Issue 4 

19632 Format reorganized. 

19633 Exceptions to Utility Syntax Guidelines conformance noted. 

19634 Internationalized environment variable support mandated. 

19635 Issue 5 

19636 Correction to the first format string in STDOUT. 

19637 The interpretation of the YY component of the -c cutoff argument is noted. 

19638 Issue 6 

19639 The obsolescent SYNOPSIS is removed, removing the -lp option. 

19640 The Open Group corrigenda item U025/5 has been applied, correcting text in the OPTIONS 

19641 section. 

19642 The normative text is reworded to avoid use of the term "must” for application requirements. 
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19643 NAME 

19644 getconf — get configuration values 

19645 SYNOPSIS 

19646 man getconf [ —v specification ] system_var 

19647 man getconf [ —v specification ] path_var pathname 

19648 DESCRIPTION 

19649 In the first synopsis form, the getconf utility shall write to the standard output the value of the 

19650 variable specified by the system_var operand. 

19651 In the second synopsis form, the getconf utility shall write to the standard output the value of the 

19652 variable specified by the pcith_var operand for the path specified by the pathname operand. 

19653 The value of each configuration variable shall be determined as if it were obtained by calling the 

19654 function from which it is defined to be available by this volume of IEEE Std. 1003.1-200x or by 

19655 the System Interfaces volume of IEEE Std. 1003.1-200x (see the OPERANDS section). The value 

19656 shall reflect conditions in the current operating environment. 

19657 OPTIONS 

19658 The getconf utility shall conform to the System Interface Definitions volume of I 

19659 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

19660 The following option shall be supported: 

19661 -v specification 

19662 man Indicate a specific specification and version for which configuration variables shall I 

19663 be determined. If this option is not specified, the values returned correspond to an I 

19664 implementation default conforming compilation environment. 

19665 If the command: 

19666 getconf _XBS5_ILP32_OFF32 

19667 

19668 

19669 

19670 

19671 

19672 

19673 If the command: 

19674 getconf _XBS5_ILP32_OFFBIG 

19675 

19676 

19677 

19678 

19679 

19680 

19681 If the command: 

19682 getconf _XBS5_LP64_OFF64 

19683 

19684 


does not write l\n" or "undef ined\n" to standard output, then commands of 

the form: 


does not write l\n" or "undef ined\n" to standard output, then commands of 
the form: 

getconf -v XBS5_ILP32_OFFBIG ... 

determine values for configuration variables corresponding to the 
XBS5_ILP32_OFFBIG compilation environment specified in c89 on page 246, 
EXTENDED DESCRIPTION. 


does not write l\n" or "undef ined\n" to standard output, then commands of 
the form: 

getconf -v XBS5_ILP32_OFF32 ... 

determine values for configuration variables corresponding to the 
XBS5_ILP32_OFF32 compilation environment specified in c89 on page 246, 
EXTENDED DESCRIPTION. 


The following option shall be supported: 

-v specification 

Indicate a specific specification and version for which configuration variables shall 
be determined. If this option is not specified, the values returned correspond to an 
implementation default conforming compilation environment. 
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19685 getconf —v XBS5_LP64_OFF64 ... 

19686 determine values for configuration variables corresponding to the 

19687 XBS5_LP64_OFF64 compilation environment specified in c89 on page 246, 

19688 EXTENDED DESCRIPTION. 

19689 If the command: 


19690 getconf _XBS5_LPBIG_OFFBIG 

19691 does not write l\n" or "undef ined\n" to standard output, then commands of 

19692 the form: 

19693 getconf —v XBS5_LPBIG_OFFBIG . . . 

19694 determine values for configuration variables corresponding to the 

19695 XBS5_LPBIG_OFFBIG compilation environment specified in c89 on page 246, 

19696 EXTENDED DESCRIPTION. 


19697 OPERANDS 

19698 The following operands shall be supported: 


19699 

19700 

19701 


pathjvar A name of a configuration variable. All of the variables in the pathconf( ) function 
defined in the System Interfaces volume of IEEE Std. 1003.1-200x are supported 
and the implementation may add other local variables. 


19702 


pathname A path name for which the variable specified by path_var is to be determined. 


19703 

19704 

19705 

19706 


systemjvar A name of a configuration variable. All of the variables in the confstr( ) and 
sysconf() functions defined in the System Interfaces volume of 
IEEE Std. 1003.1-200x shall be supported and the implementation may add other 
local values. 


19707 Notes to Reviewers 

19708 This section with side shading will not appear in the final copy. - Ed. 


19709 Dl, XCU, ERN 256 notes an issue - we may change the names of these macros for 

19710 the next revision. 


19711 man When the symbol listed in the first column of the following table is used as the 

19712 system_var operand, getconf yields the same value as confstr( ) when called with the 

19713 value in the second column: 


518 


Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


getconf 


19714 


19715 


systemjvar 

confstrt ) Name Value 

19716 


PATH 

_CS_PATH 

19717 


XBS5_ILP32_OFF32_CFLAGS 

_CS_XBS5_ILP32_OFF32_CFLAGS 

19718 


XBS5_ILP32_OFF32_LDFLAGS 

CS XBS5 ILP32 OFF32 LDFLAGS 

19719 


XBS5_ILP32_OFF32_LIBS 

_CS_XBS5_ILP32_OFF32_LIBS 

19720 


XBS5_ILP32_OFF32_LINTFLAGS 

_CS_XBS5_ILP32_OFF32_LINTFLAGS 

19721 


XBS5_ILP32_OFFBIG_CFLAGS 

_CS_XBS5_ILP32_OFFBIG_CFLAGS 

19722 


XBS5_ILP32_OFFBIG_LDFLAGS 

_CS_XBS5_ILP32_OFFBIG_LDFLAGS 

19723 


XBS5_ILP32_OFFBIG_LIBS 

_CS_XBS5_ILP32_OFFBIG_LIBS 

19724 


XBS5_ILP32_OFFBIG_LINTFLAGS 

_CS_XBS5_ILPBIG_OFF32_LINTFLAGS 

19725 


XBS5_LP64_OFF64_CFLAGS 

_CS_XBS5_LP64_OFF64_CFLAGS 

19726 


XBS5_LP64_OFF64_LDFLAGS 

_CS_XBS5_LP64_OFF64_LDFLAGS 

19727 


XBS5_LP64_OFF64_LIBS 

_CS_XBS5_LP64_OFF64_LIBS 

19728 


XBS5_LP64_OFF64_LINTFLAGS 

_CS_XBS5_LP64_OFF64_LINTFLAGS 

19729 


XBS5_LPBIG_OFFBIG_CFLAGS 

CS XBS5 1 PBTG OFFBIG GFLAGS 

19730 


XBS5_LPBIG_OFFBIG_LDFLAGS 

_CS_XBS5_LPBIG_OFFBIG_LDFLAGS 

19731 


XBS5_LPBIG_OFFBIG_LIBS 

_CS_XBS5_LPBIG_OFFBIG_LIBS 

19732 


XBS5_LPBIG_OFFBIG_LINTFLAGS 

_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS 


19733 STDIN 

19734 Not used. 

19735 INPUT FILES 

19736 None. 


19737 ENVIRONMENT VARIABLES 

19738 The following environment variables shall affect the execution of getconf: 


19739 

19740 

19741 

19742 

19743 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


19744 

19745 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


19746 

19747 

19748 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


19749 LC_MESSAGES 

19750 Determine the locale that should be used to affect the format and contents of 

19751 diagnostic messages written to standard error. 

19752 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


19753 ASYNCHRONOUS EVENTS 

19754 Default. 


19755 STDOUT 

19756 If the specified variable is defined on the system and its value is described to be available from 

19757 the confstr () function defined in the System Interfaces volume of IEEE Std. 1003.1-200x, its value 

19758 shall be written in the following format: 

19759 "%s\n", <value> 
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19760 Otherwise, if the specified variable is defined on the system, its value shall be written in the 

19761 following format: 

19762 "%d\n", <value> 

19763 If the specified variable is valid, but is undefined on the system, getconf shall write using the 

19764 following format: 

19765 "undef ined\n" 

19766 If the variable name is invalid or an error occurs, nothing shall be written to standard output. 

19767 STDERR 

19768 Used only for diagnostic messages. 

19769 OUTPUT FILES 

19770 None. 

19771 EXTENDED DESCRIPTION 

19772 None. 

19773 EXIT STATUS 

19774 The following exit values shall be returned: 

19775 0 The specified variable is valid and information about its current state was written 

19776 successfully. 

19777 >0 An error occurred. 

19778 CONSEQUENCES OF ERRORS 

19779 Default. 

19780 APPLICATION USAGE 

19781 None. 

19782 EXAMPLES 

19783 The following example illustrates the value of |NGROUPS_MAX}: 

19784 getconf NGROUPS_MAX 

19785 The following example illustrates the value of |NAME_MAX} for a specific directory: 

19786 getconf NAME_MAX /usr 

19787 The following example shows how to deal more carefully with results that might be unspecified: 

19788 if value=$ (getconf PATH_MAX /usr); then 

19789 if [ "$value" = "undefined" ]; then 

19790 echo PATH_MAX in /usr is infinite. 

19791 else 

19792 echo PATH_MAX in /usr is $value. 

19793 fi 

19794 else 

19795 echo Error in getconf. 

19796 fi 

19797 Note that: 

19798 sysconf (_SC_POSIX_C_BIND) ; 

19799 and: 
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19800 

19801 

19802 

19803 

19804 

19805 

19806 

19807 

19808 

19809 

19810 

19811 

19812 

19813 

19814 

19815 

19816 

19817 

19818 

19819 

19820 

19821 

19822 

19823 

19824 

19825 

19826 

19827 

19828 

19829 

19830 

19831 

19832 

19833 

19834 

19835 

19836 

19837 

19838 

19839 

19840 

19841 


system("getconf POSIX2_C_BIND"); 

in a C program could give different answers. The sysconf( ) call supplies a value that corresponds 
to the conditions when the program was either compiled or executed, depending on the 
implementation; the system () call to getconf always supplies a value corresponding to conditions 
when the program is executed. 

RATIONALE 

The original need for this utility, and for the confstr( ) function, was to provide a way of finding 
the configuration-defined default value for the PATH environment variable. Since PATH can be 
modified by the user to include directories that could contain utilities replacing the standard 
utilities, shell scripts need a way to determine the system-supplied PATH environment variable 
value that contains the correct search path for the standard utilities. It was later suggested that 
access to the other variables described in this volume of IEEE Std. 1003.1-200x could also be 
useful to applications. 

The following two function calls in a C program could give different answers: 

sysconf(_SC_POSIX_C_BIND) ; 
system("getconf POSIX2_C_BIND"); 

The sysconf () call supplies a value that corresponds to the conditions when the program was 
either compiled or executed, depending on the implementation; the system() call to getconf 
always supplies a value corresponding to conditions when the program is executed. 

This functionality of getconf would not be adequately subsumed by another command such as: 

grep var /etc/conf 

because such a strategy would provide correct values for neither those variables that can vary at I 
runtime, nor those that can vary depending on the path. I 

Early proposal versions of getconf specified exit status 1 when the specified variable was valid, 
but not defined on the system. The output string "undefined" is now used to specify this case 
with exit code 0 because so many things depend on an exit code of zero when an invoked utility 
is successful. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

c89 the System Interfaces volume of IEEE Std. 1003.1-200x, confstr( ), pathconf (), sysconf () 

CHANGE HISTORY 

First released in Issue 4. 

Issue 4, Version 2 

The following changes are made in the table of values for system_mr: 

• Names beginning with POSIX_ are changed to begin with _POSIX_. 

• Names beginning with XOPEN_ are changed to begin with _XOPEN_. 

. {MN_NMAX[ is changed to |NL_MAX}. 

. |NL_SET_MAX} is changed to |NL_SETMAX}. 

. |NL_TEXT_MAX} is changed to |NL_TEXTMAX}. 

. The _XOPEN_CRYPT, _XOPEN_ENH_I18N, and _XOPEN_SHM configuration variables are 
added to the list. 
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19842 

19843 

19844 

19845 

19846 

19847 

19848 

19849 

19850 

19851 

19852 

19853 

19854 


Issue 5 

In the OPERANDS section: 

• {NL_MAX} is changed to |NL_NMAX}. 

• Entries beginning NL_ are deleted from the list of standard configuration variables. 

• The list of variables previously marked UX is merged with the list marked EX. 

• Operands are added to support new Option Groups. 

• Operands are added so that getconf can determine supported programming environments. 

Issue 6 

The Open Group corrigenda item U029/4 has been applied, correcting the example command in 
the last paragraph of the OPTIONS section. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• Operands are added to determine supported programming environments. 
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19855 NAME 

19856 getopts — parse utility options 

19857 SYNOPSIS 

19858 getopts optstring name [ arg ...] 

19859 DESCRIPTION 

19860 The getopts utility can be used to retrieve options and option-arguments from a list of 

19861 parameters. It shall support the Utility Syntax Guidelines 3 to 10, inclusive, described in the I 

19862 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax I 

19863 Guidelines. I 

19864 Each time it is invoked, the getopts utility shall place the value of the next option in the shell 

19865 variable specified by the name operand and the index of the next argument to be processed in the 

19866 shell variable OPTIND. Whenever the shell is invoked, OPTIND shall be initialized to 1. 

19867 When the option requires an option-argument, the getopts utility shall place it in the shell 

19868 variable OPTARG. If no option was found, or if the option that was found does not have an 

19869 option-argument, OPTARG shall be unset. 

19870 If an option character not contained in the optstring operand is found where an option character 

19871 is expected, the shell variable specified by name shall be set to the question-mark (' ?') character. 

19872 In this case, if the first character in optstring is a colon (' :' ), the shell variable OPTARG shall be 

19873 set to the option character found, but no output shall be written to standard error; otherwise, the 

19874 shell variable OPTARG shall be unset and a diagnostic message shall be written to standard 

19875 error. This condition shall be considered to be an error detected in the way arguments were 

19876 presented to the invoking application, but shall be not an error in getopts processing. 

19877 If an option-argument is missing: 

19878 • If the first character of optstring is a colon, the shell variable specified by name shall be set to 

19879 the colon character and the shell variable OPTARG shall be set to the option character found. 

19880 • Otherwise, the shell variable specified by name shall be set to the question-mark character, 

19881 the shell variable OPTARG shall be unset, and a diagnostic message shall be written to 

19882 standard error. This condition shall be considered to be an error detected in the way 

19883 arguments were presented to the invoking application, but shall not be an error in getopts 

19884 processing; a diagnostic message shall be written as stated, but the exit status shall be zero. 

19885 When the end of options is encountered, the getopts utility shall exit with a return value greater 

19886 than zero; the shell variable OPTIND shall be set to the index of the first non-option-argument, 

19887 where the first "—" argument is considered to be an option-argument if there are no other non- 

19888 option-arguments appearing before it, or the value "$#"+1 if there are no non-option- 

19889 arguments; the name variable shall be set to the question-mark character. Any of the following 

19890 shall identify the end of options: the special option "—", finding an argument that does not 

19891 begin with a ' - ', or encountering an error. 

19892 The shell variables OPTIND and OPTARG shall be local to the caller of getopts and shall not be 

19893 exported by default. 

19894 The shell variable specified by the name operand, OPTIND and OPTARG shall affect the current 

19895 shell execution environment; see Section 2.12 on page 90. 

19896 If the application sets OPTIND to the value 1, a new set of parameters can be used: either the 

19897 current positional parameters or new arg values. Any other attempt to invoke getopts multiple 

19898 times in a single shell execution environment with parameters (positional parameters or arg 

19899 operands) that are not the same in all invocations, or with an OPTIND value modified to be a 

19900 value other than 1, produces unspecified results. 
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19901 OPTIONS 

19902 None. 


19903 OPERANDS 

19904 The following operands shall be supported: 


19905 

19906 

19907 

19908 

19909 

19910 

19911 

19912 

19913 

19914 

19915 

19916 

19917 

19918 

19919 


optstring A string containing the option characters recognized by the utility invoking getopts. 

If a character is followed by a colon, the option shall be expected to have an 
argument, which should be supplied as a separate argument. Applications should 
specify an option character and its option-argument as separate arguments, but 
getopts shall interpret the characters following an option character requiring 
arguments as an argument whether or not this is done. An explicit null option- 
argument need not be recognized if it is not supplied as a separate argument when 
getopts is invoked. (See also the getopt() function defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x.) The characters question-mark and colon shall I 
not be used as option characters by an application. The use of other option I 
characters that are not alphanumeric produces unspecified results. If the option- 
argument is not supplied as a separate argument from the option character, the 
value in OPTARG shall be stripped of the option character and the ' - '. The first 
character in optstring determines how getopts behaves if an option character is not 
known or an option-argument is missing. 


19920 name The name of a shell variable that shall be set by the getopts utility to the option 

19921 character that was found. 


19922 The getopts utility by default shall parse positional parameters passed to the invoking shell 

19923 procedure. If arg s are given, they shall be parsed instead of the positional parameters. 

19924 STDIN 

19925 Not used. 


19926 INPUT FILES 

19927 None. 


19928 ENVIRONMENT VARIABLES 

19929 The following environment variables shall affect the execution of getopts: 


19930 

19931 

19932 

19933 

19934 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


19935 

19936 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


19937 

19938 

19939 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


19940 LC_MESSAGES 

19941 Determine the locale that should be used to affect the format and contents of 

19942 diagnostic messages written to standard error. 


19943 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

19944 OPTIND This variable shall be used by the getopts utility as the index of the next argument 

19945 to be processed. 
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19946 

19947 

19948 

19949 

19950 

19951 

19952 

19953 

19954 

19955 

19956 

19957 

19958 

19959 

19960 

19961 

19962 

19963 

19964 

19965 

19966 

19967 

19968 

19969 

19970 

19971 

19972 

19973 

19974 

19975 

19976 

19977 

19978 

19979 

19980 

19981 

19982 

19983 

19984 

19985 

19986 

19987 

19988 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Whenever an error is detected and the first character in the optstring operand is not a colon 
(' :'a diagnostic message shall be written to standard error with the following information in 
an unspecified format: 

• The invoking program name shall be identified in the message. The invoking program name 
shall be the value of the shell special parameter 0 (see Section 2.5.2 on page 43) at the time the 
getopts utility is invoked. A name equivalent to: 

basename "$0" 

may be used. 

• If an option is found that was not specified in optstring, this error is identified and the invalid 
option character shall be identified in the message. 

• If an option requiring an option-argument is found, but an option-argument is not found, 
this error shall be identified and the invalid option character shall be identified in the 
message. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 An option, specified or unspecified by optstring, was found. 

>0 The end of options was encountered or an error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Since getopts affects the current shell execution environment, it is generally provided as a shell 
regular built-in. If it is called in a subshell or separate utility execution environment, such as one 
of the following: 

(getopts abc value "$@") 
nohup getopts .. . 
find . —exec getopts ... \; 

it does not affect the shell variables in the caller's environment. 

Note that shell functions share OPTIND with the calling shell even though the positional 
parameters are changed. If the calling shell and any of its functions uses getopts to parse 
arguments, the results are unspecified. 

EXAMPLES 

The following example script parses and displays its arguments: 

aflag= 
bflag= 
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19989 while getopts ab: name 

19990 do 

19991 case $name in 

19992 a) aflag=l;; 

19993 b) bf lag=l 

19994 b va 1 = " $ OP TARG " ; ; 

19995 ?) printf "Usage: %s: [-a] [—b value] args\n" $0 

19996 exit 2;; 

19997 esac 

19998 done 

19999 if [ ! —z "$aflag" ]; then 

20000 printf "Option —a specified\n" 

20001 fi 

20002 if [ ! -z " $bf lag" ]; then 

20003 printf 'Option —b "%s" specified\n' "$bval" 

20004 fi 

20005 shift $ ( ($OPTIND - 1)) 

20006 printf "Remaining arguments are: %s\n" "$*" 

20007 RATIONALE 

20008 The getopts utility was chosen in preference to the System V getopt utility because getopts handles 

20009 option-arguments containing <blank> characters. 

20010 The OPTARG variable is not mentioned in the ENVIRONMENT VARIABLES section because it 

20011 does not affect the execution of getopts; it is one of the few "output-only" variables used by the 

20012 standard utilities. 

20013 The colon is not allowed as an option character because that is not historical behavior, and it 

20014 violates the Utility Syntax Guidelines. The colon is now specified to behave as in the KomShell 

20015 version of the getopts utility; when used as the first character in the optstring operand, it disables 

20016 diagnostics concerning missing option-arguments and unexpected option characters. This 

20017 replaces the use of the OPTERR variable that was specified in an early proposal. 

20018 The formats of the diagnostic messages produced by the getopts utility and the getopt () function 

20019 are not fully specified because implementations with superior ("friendlier") formats objected to 

20020 the formats used by some historical implementations. The standard developers considered it 

20021 important that the information in the messages used be uniform between getopts and getopt (). 

20022 Exact duplication of the messages might not be possible, particularly if a utility is built on 

20023 another system that has a different getopt () function, but the messages must have specific 

20024 information included so that the program name, invalid option character, and type of error can 

20025 be distinguished by a user. 

20026 Only a rare application program intercepts a getopts standard error message and wants to parse 

20027 it. Therefore, implementations are free to choose the most usable messages they can devise. The 

20028 following formats are used by many historical implementations: 

20029 "%s: illegal option — %c\n", <program name>, <option character> 

20030 "%s: option requires an argument — %c\n", <program name >, \ 

20031 <option character> 

20032 Historical shells with built-in versions of getopt () or getopts have used different formats, 

20033 frequently not even indicating the option character found in error. 
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20034 FUTURE DIRECTIONS 

20035 None. 

20036 SEE ALSO 

20037 The System Interfaces volume of IEEE Std. 1003.1-200x, get opt {) 

20038 CHANGE HISTORY 

20039 First released in Issue 4. 

20040 Issue 6 

20041 The normative text is reworded to avoid use of the term "must” for application requirements. 
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20042 NAME 

20043 grep — search a file for a pattern 

20044 SYNOPSIS 

20045 grep [—E | —F] [—c | —1 | —q] [—insvx] —e pattern_list. . . 

20046 [—f pattern_file] . . . [file. . . ] 

20047 grep [— E | —F] [—c | —1 I —q] [-insvx] [—e pattern_list ] . . . 

20048 —f pattern_file...[file...] 


20049 grep [—E | —F] [—c | —1 | —q] [—insvx] pattern_list[file...] 


20050 DESCRIPTION 

20051 The grep utility shall search the input files, selecting lines matching one or more patterns; the 

20052 types of patterns are controlled by the options specified. The patterns are specified by the -e 

20053 option, -f option, or the pattern Jist operand. The pattern Jist’s value shall consist of one or more 

20054 patterns separated by <newline> characters; the pattern Jile' s contents shall consist of one or 

20055 more patterns terminated by <newline> characters. By default, an input line shall be selected if 

20056 any pattern, treated as an entire basic regular expression (BRE) as described in the System 

20057 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.3, Basic Regular Expressions, 

20058 matches any part of the line; a null BRE shall match every line. By default, each selected input 

20059 line shall be written to the standard output. 

20060 Regular expression matching shall be based on text lines. Since a <newline> character separates 

20061 or terminates patterns (see the -e and -f options below), regular expressions cannot contain a 

20062 <newline> character. Similarly, since patterns are matched against individual lines of the input, 

20063 there is no way for a pattern to match a <newline> character found in the input. 


20064 OPTIONS 

20065 The grep utility shall conform to the System Interface Definitions volume of 

20066 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

20067 The following options shall be supported: 


20068 -E 

20069 

20070 

20071 


Match using extended regular expressions. Treat each pattern specified as an ERE, 
as described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Section 9.4, Extended Regular Expressions. If any entire ERE pattern matches some 
part of an input line, the line shall be matched. A null ERE shall match every line. 


20072 -F 

20073 

20074 


Match using fixed strings. Treat each pattern specified as a string instead of a 
regular expression. If an input line contains any of the patterns as a contiguous 
sequence of bytes, the line shall be matched. A null string shall match every line. 


20075 -C 


Write only a count of selected lines to standard output. 


20076 

20077 

20078 

20079 

20080 
20081 
20082 

20083 

20084 


-e pattern Jist 

Specify one or more patterns to be used during the search for input. The 
application shall ensure that patterns in pattern Jist are separated by a <newline> 
character. A null pattern can be specified by two adjacent <newline> characters in 
pattern Jist . Unless the -E or -F option is also specified, each pattern shall be 
treated as a BRE, as described in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 9.3, Basic Regular Expressions. Multiple -e and -f 
options shall be accepted by the grep utility. All of the specified patterns shall be 
used when matching lines, but the order of evaluation is unspecified. 


20085 -f pattern Jile 

20086 Read one or more patterns from the file named by the path name pattern Jile. 

20087 Patterns in pattern Jile shall be terminated by a <newline> character. A null pattern 


528 


Technical Standard (2000) (Draft February 29, 2000) 



20088 

20089 

20090 

20091 

20092 

20093 

20094 

20095 

20096 

20097 

20098 

20099 

20100 
20101 

20102 

20103 

20104 

20105 

20106 

20107 

20108 

20109 

20110 
20111 

20112 

20113 

20114 

20115 

20116 

20117 

20118 

20119 

20120 

20121 

20122 

20123 

20124 

20125 

20126 

20127 

20128 

20129 

20130 

20131 


Utilities 


grep 


can be specified by an empty line in pattern_file . Unless the -E or -F option is also 
specified, each pattern shall be treated as a BRE, as described in the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.3, Basic Regular 
Expressions. 

-i Perform pattern matching in searches without regard to case; see the System 

Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.2, Regular 
Expression General Requirements. 

-1 (The letter ell.) Write only the names of files containing selected lines to standard 

output. Path names shall be written once per file searched. If the standard input is 
searched, a path name of " (standard input) " shall be written, in the POSIX 
locale. In other locales, " standard input " may be replaced by something more 
appropriate in those locales. 

-n Precede each output line by its relative line number in the file, each file starting at 

line 1. The line number counter shall be reset for each file processed. 

-q Quiet. Do not write anything to the standard output, regardless of matching lines. 

Exit with zero status if an input line is selected. 

-s Suppress the error messages ordinarily written for nonexistent or unreadable files. 

Other error messages shall not be suppressed. 

-v Select lines not matching any of the specified patterns. If the -v option is not 

specified, selected lines shall be those that match any of the specified patterns. 

-x Consider only input lines that use all characters in the line to match an entire fixed 

string or regular expression to be matching lines. 

OPERANDS 

The following operands shall be supported: 

pattern Specify one or more patterns to be used during the search for input. This operand 

shall be treated as if it were specified as -e pattern Jist. 

file A path name of a file to be searched for the patterns. If no file operands are 

specified, the standard input shall be used. 

STDIN 

The standard input shall be used only if no file operands are specified. See the INPUT FILES 

section. 

INPUT FILES 

The input files shall be text files. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of grep: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi- 
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20132 

20133 

20134 

20135 

20136 

20137 

20138 

20139 

20140 

20141 

20142 

20143 

20144 

20145 

20146 

20147 

20148 

20149 

20150 

20151 

20152 

20153 

20154 

20155 

20156 

20157 

20158 

20159 

20160 
20161 

20162 

20163 

20164 

20165 

20166 

20167 

20168 


character collating elements within regular expressions. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes within regular 
expressions. 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

If the -1 option is in effect, and the -q option is not, the following shall be written for each file 
containing at least one selected input line: 

"%s\n", <file> 

Otherwise, if more than one file argument appears, and -q is not specified, the grep utility shall 
prefix each output line by: 

" % s:", <file> 

The remainder of each output line shall depend on the other options specified: 

• If the -c option is in effect, the remainder of each output line shall contain: 

"%d\n", <count> 

• Otherwise, if -c is not in effect and the -n option is in effect, the following shall be written to 
standard output: 

"%d:", <line number> 

• Finally, the following shall be written to standard output: 

"%s", <selected-line contents> 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 One or more lines were selected. 

1 No lines were selected. 

>1 An error occurred. 
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20169 CONSEQUENCES OF ERRORS 

20170 If the -q option is specified, the exit status shall be zero if an input line is selected, even if an 

20171 error was detected. Otherwise, default actions shall be performed. 

20172 APPLICATION USAGE 

20173 Care should be taken when using characters in patternjist that may also be meaningful to the 

20174 command interpreter. It is safest to enclose the entire patternjist argument in single quotes: 

20175 ' . . . ' 

20176 The -e patternjist option has the same effect as the patternjist operand, but is useful when 

20177 patternjist begins with the hyphen delimiter. It is also useful when it is more convenient to 

20178 provide multiple patterns as separate arguments. 

20179 Multiple -e and -f options are accepted and grep uses all of the patterns it is given while 

20180 matching input text lines. (Note that the order of evaluation is not specified. If an 

20181 implementation finds a null string as a pattern, it is allowed to use that pattern first, matching 

20182 every line, and effectively ignore any other patterns.) 

20183 The -q option provides a means of easily determining whether or not a pattern (or string) exists 

20184 in a group of files. When searching several files, it provides a performance improvement 

20185 (because it can quit as soon as it finds the first match) and requires less care by the user in 

20186 choosing the set of files to supply as arguments (because it exits zero if it finds a match even if 

20187 grep detected an access or read error on earlier file operands). 

20188 EXAMPLES 

20189 1. 

20190 

20191 

20192 2 . 

20193 

20194 

20195 

20196 3 . 

20197 

20198 

20199 

20200 

20201 4 . 

20202 

20203 

20204 

20205 

20206 RATIONALE 

20207 This grep has been enhanced in an upward-compatible way to provide the exact functionality of 

20208 the historical egrep and fgrep commands as well. It was the clear intention of the standard 

20209 developers to consolidate the three greps into a single command. 


To find all uses of the word "Posix" (in any case) in file text.mm and write with line 
numbers: 

grep —i —n posix text.mm 

To find all empty lines in the standard input: 

grep "$ 

or: 

grep —v . 

Both of the following commands print all lines containing strings " abc " or " de f " or both: 

grep -E 'abc 
def' 

grep -F 'abc 
def' 

Both of the following commands print all lines matching exactly " abc " or " def": 

grep —E '"abc$ 

A def$' 

grep —F —x ' abc 
def' 
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20210 The old egrep and fgrep commands are likely to be supported for many years to come as 

20211 implementation extensions, allowing historical applications to operate unmodified. 

20212 Historical implementations usually silently ignored all but one of multiply-specified -e and -f 

20213 options, but were not consistent as to which specification was actually used. 

20214 The -b option was omitted from the OPTIONS section because block numbers are 

20215 implementation-dependent. 

20216 The System V restriction on using - to mean standard input was omitted. 

20217 A definition of action taken when given a null BRE or ERE is specified. This is an error condition 

20218 in some historical implementations. 

20219 The -1 option previously indicated that its use was undefined when no files were explicitly 

20220 named. This behavior was historical and placed an unnecessary restriction on future 

20221 implementations. It has been removed. 

20222 The historical BSD grep -s option practice is easily duplicated by redirecting standard output to 

20223 /dev/null. The -s option required here is from System V. 

20224 The -x option, historically available only with fgrep, is available here for all of the non- 

20225 obsolescent versions. 

20226 FUTURE DIRECTIONS 

20227 None. 

20228 SEE ALSO 

20229 sed 

20230 CHANGE HISTORY 

20231 First released in Issue 2. 

20232 Issue 4 

20233 Aligned with the ISO/IEC 9945-2:1993 standard. 

20234 Issue 6 

20235 The Open Group corrigenda item U029/5 has been applied, correcting the SYNOPSIS. 

20236 The normative text is reworded to avoid use of the term "must” for application requirements. 
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20237 NAME 

20238 hash — remember or report utility locations 

20239 SYNOPSIS 

20240 xsi hash [utility...] 

20241 hash -r 

20242 

20243 DESCRIPTION 

20244 The hash utility shall affect the way the current shell environment remembers the locations of 

20245 utilities found as described in Section 2.9.1.1 on page 69. Depending on the arguments specified, 

20246 it shall add utility locations to its list of remembered locations or it shall purge the contents of 

20247 the list. When no arguments are specified, it shall report on the contents of the list. 

20248 Utilities provided as built-ins to the shell shall not be reported by hash. 

20249 OPTIONS 

20250 The hash utility shall conform to the System Interface Definitions volume of I 

20251 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

20252 The following option shall be supported: 

20253 -r Forget all previously remembered utility locations. 

20254 OPERANDS 

20255 The following operand shall be supported: 

20256 utility The name of a utility to be searched for and added to the list of remembered 

20257 locations. If utility contains one or more slashes, the results are unspecified. 

20258 STDIN 

20259 Not used. 

20260 INPUT FILES 

20261 None. 


20262 ENVIRONMENT VARIABLES 

20263 The following environment variables shall affect the execution of hash: 


20264 

20265 

20266 

20267 

20268 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


20269 LC_ALL If set to a non-empty string value, override the values of all the other 

20270 internationalization variables. 


20271 

20272 

20273 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


20274 

20275 

20276 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


20277 

20278 

20279 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Determine the location of utility, as described in the System Interface Definitions I 

volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 
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20280 ASYNCHRONOUS EVENTS 

20281 Default. 

20282 STDOUT 

20283 The standard output of hash shall be used when no arguments are specified. Its format is 

20284 unspecified, but includes the path name of each utility in the list of remembered locations for the 

20285 current shell environment. This list shall consist of those utilities named in previous hash 

20286 invocations that have been invoked, and may contain those invoked and found through the 

20287 normal command search process. 

20288 STDERR 

20289 Used only for diagnostic messages. 

20290 OUTPUT FILES 

20291 None. 

20292 EXTENDED DESCRIPTION 

20293 None. 

20294 EXIT STATUS 

20295 The following exit values shall be returned: 

20296 0 Successful completion. 

20297 >0 An error occurred. 

20298 CONSEQUENCES OF ERRORS 

20299 Default. 

20300 APPLICATION USAGE 

20301 Since hash affects the current shell execution environment, it is always provided as a shell 

20302 regular built-in. If it is called in a separate utility execution environment, such as one of the 

20303 following: 

20304 nohup hash —r 

20305 find . —type f | xargs hash 

20306 it does not affect the command search process of the caller's environment. 

20307 The hash utility may be implemented as an alias—for example, alias -t -, in which case utilities 

20308 found through normal command search are not listed by the hash command. 

20309 The effects of hash -r can also be achieved portably by resetting the value of PATH ; in the 

20310 simplest form, this can be: 

20311 PATH=" $PATH" 

20312 The use of hash with utility names is unnecessary for most applications, but may provide a 

20313 performance improvement on a few implementations; normally, the hashing process is included 

20314 by default. 

20315 EXAMPLES 

20316 None. 

20317 RATIONALE 

20318 None. 

20319 FUTURE DIRECTIONS 

20320 None. 
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20321 SEE ALSO 

20322 Section 2.9.1.1 on page 69 

20323 CHANGE HISTORY 

20324 First released in Issue 2. 

20325 Issue 4 

20326 Relocated from the sh description to reflect its status as a regular built-in utility. 
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20327 NAME 

20328 head — copy the first part of files 

20329 SYNOPSIS 

20330 head [—n number] [file. . .] 

20331 DESCRIPTION 

20332 The head utility shall copy its input files to the standard output, ending the output for each file at 

20333 a designated point. 

20334 Copying shall end at the point in each input file indicated by the -n number option. The option- 

20335 argument number shall be counted in units of lines. 

20336 OPTIONS 

20337 The head utility shall conform to the System Interface Definitions volume of I 

20338 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

20339 The following option shall be supported: 

20340 -n number The first number lines of each input file shall be copied to standard output. The I 

20341 application shall ensure that the number option-argument is a positive decimal I 

20342 integer. I 

20343 If no options are specified, head shall act as if -n 10 had been specified. 

20344 OPERANDS 

20345 The following operand shall be supported: 

20346 file A path name of an input file. If no file operands are specified, the standard input 

20347 shall be used. 

20348 STDIN 

20349 The standard input shall be used only if no file operands are specified. See the INPUT FILES 

20350 section. 


20351 INPUT FILES 

20352 Input files shall be text files, but the line length is not restricted to {LINE_MAX} bytes. 


20353 ENVIRONMENT VARIABLES 

20354 The following environment variables shall affect the execution of head: 


20355 

20356 

20357 

20358 

20359 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


20360 

20361 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


20362 

20363 

20364 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


20365 LC_MESSAGES 

20366 Determine the locale that should be used to affect the format and contents of 

20367 diagnostic messages written to standard error. 

20368 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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20369 

20370 

20371 

20372 

20373 

20374 

20375 

20376 

20377 

20378 

20379 

20380 

20381 

20382 

20383 

20384 

20385 

20386 

20387 

20388 

20389 

20390 

20391 

20392 

20393 

20394 

20395 

20396 

20397 

20398 

20399 

20400 

20401 

20402 

20403 

20404 

20405 

20406 

20407 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall contain designated portions of the input files. 

If multiple file operands are specified, head shall precede the output for each with the header: 

"\n==> %s <==\n", <pathname> 

except that the first header written shall not include the initial <newline> character. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The obsolescent -number form is withdrawn in this version. Applications should use the -n 
number option. 

EXAMPLES 

To write the first ten lines of all files (except those with a leading period) in the directory: 
head * 

RATIONALE 

Although it is possible to simulate head with sed lOq for a single file, the standard developers 
decided that the popularity of head on historical BSD systems warranted its inclusion alongside 
tail. 

This standard version of head follows the Utility Syntax Guidelines. The -n option was added to 
this new interface so that head and tail would be more logically related. 

There is no -c option (as there is in tail) because it is not historical practice and because other 
utilities in this volume of IEEE Std. 1003.1-200x provide similar functionality. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

sed, tail 

CHANGE HISTORY 

First released in Issue 4. 
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20408 

20409 

20410 


Issue 6 

The obsolescent -number form is withdrawn. 

The normative text is reworded to avoid use of the term "must” for application requirements. 


538 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


iconv 


20411 NAME 

20412 iconv — codeset conversion 


20413 SYNOPSIS 

20414 iconv [—cs] — f fromcode —t tocode [file . . .] 

20415 iconv —1 


20416 DESCRIPTION 

20417 The iconv utility shall convert the encoding of characters in file from one codeset to another and 

20418 write the results to standard output. 

20419 When the options indicate that charmap files are used to specify the codesets (see OPTIONS), 

20420 the codeset conversion shall be accomplished by performing a logical join on the symbolic 

20421 character names in the two charmaps. The implementation need not support the use of charmap 

20422 files for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on the system. 


20423 OPTIONS 

20424 The iconv utility shall conform to the System Interface Definitions volume of 

20425 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

20426 The following options shall be supported: 


20427 -C 

20428 

20429 

20430 

20431 


Omit any invalid characters from the output. When -c is not used, the results of 
encountering invalid characters in the input stream (either those that are not valid 
members of the fromcode or those that have no corresponding value in tocode) shall 
be specified in the system documentation. The presence or absence of -c shall not 
affect the exit status of iconv. 


20432 

20433 

20434 

20435 

20436 

20437 

20438 

20439 

20440 


—f fromcode Identify the codeset of the input file. If the option-argument contains a slash 
character, iconv shall attempt to use it as the path name of a charmap file, as 
defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Section 6.4, Character Set Description File. If the path name does not represent a 
valid, readable charmap file, the results are undefined. If the option-argument does 
not contain a slash, it shall be considered the name of one of the codeset 
descriptions provided by the system, in an unspecified format. The valid values of 
the option-argument without a slash are implementation-dependent. If this option 
is omitted, the codeset of the current locale shall be used. 


20441 -1 Write all supported fromcode and tocode values to standard output in an unspecified 

20442 format. 


20443 -S 

20444 

20445 

20446 

20447 


Suppress any messages written to standard error concerning invalid characters. 
When -s is not used, the results of encountering invalid characters in the input 
stream (either those that are not valid members of the fromcode or those that have 
no corresponding value in tocode) shall be specified in the system documentation. 
The presence or absence of -s shall not affect the exit status of iconv. 


20448 -t tocode Identify the codeset to be used for the output file. The semantics are equivalent to 

20449 the -f fromcode option. 


20450 If either -f or -t represents a charmap file, but the other does not (or is omitted), or both -f and 

20451 -t are omitted, the results are undefined. 


20452 OPERANDS 

20453 The following operand shall be supported: 

20454 file A path name of an input file. If no file operands are specified, or if a file operand is I 

20455 ' —the standard input shall be used. I 
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20456 STDIN 

20457 The standard input shall be used only if no file operands are specified, or if a file operand is ' —'. 

20458 INPUT FILES 

20459 The input file shall be a text file. 


20460 ENVIRONMENT VARIABLES 

20461 The following environment variables shall affect the execution of iconv: 

20462 

20463 

20464 

20465 

20466 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

20467 

20468 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

20469 

20470 

20471 

20472 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). During translation of the file, this variable is superseded by the use of 
the fromcode option-argument. 

20473 

20474 

20475 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

20476 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

20477 ASYNCHRONOUS EVENTS 

20478 Default. 


20479 STDOUT 

20480 When the -1 option is used, the standard output shall contain all supported fromcode and tocode 

20481 values, written in an unspecified format. 

20482 When the -1 option is not used, the standard output shall contain the sequence of characters 

20483 read from the input files, translated to the specified codeset. Nothing else shall be written to the 

20484 standard output. 

20485 STDERR 

20486 Used only for diagnostic messages. 

20487 OUTPUT FILES 

20488 None. 


20489 EXTENDED DESCRIPTION 

20490 None. 


20491 EXIT STATUS 

20492 The following exit values shall be returned: 

20493 0 Successful completion. 

20494 >0 An error occurred. 


20495 CONSEQUENCES OF ERRORS 

20496 Default. 
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20497 APPLICATION USAGE 

20498 The user must ensure that both charmap files use the same symbolic names for characters the I 

20499 two codesets have in common. I 

20500 EXAMPLES 

20501 The following example converts the contents of file mail.x400 from the ISO/IEC 6937:1994 

20502 standard codeset to the ISO/IEC 8859-1:1998 standard codeset, and stores the results in file I 

20503 mail.local: I 

20504 iconv —f IS6937 — t IS8859 mail.x400 > mail.local 

20505 RATIONALE 

20506 The iconv utility can be used portably only when the user provides two charmap files as option- I 

20507 arguments. This is because a single charmap provided by the user cannot reliably be joined with I 

20508 the names in a system-provided character set description. The valid values for fromcode and I 

20509 tocode are implementation-dependent and do not have to have any relation to the charmap I 

20510 mechanisms. As an aid to interactive users, the -1 option was adopted from the Plan 9 operating I 

20511 system. It writes information concerning these implementation-dependent values. The format is I 

20512 unspecified because there are many possible useful formats that could be chosen, such as a I 

20513 matrix of valid combinations of fromcode and tocode. The-1 option is not intended for shell script I 

20514 usage; portable applications will have to use charmaps. I 

20515 FUTURE DIRECTIONS 

20516 None. 

20517 SEE ALSO 

20518 gencat 

20519 CHANGE HISTORY 

20520 First released in Issue 3. 

20521 Issue 4 

20522 Format reorganized. 

20523 Utility Syntax Guidelines support mandated. 

20524 Internationalized environment variable support mandated. 

20525 Issue 6 

20526 This utility has been rewritten to align with the IEEE P1003.2b draft standard. Specifically, the I 

20527 ability to use charmap files for conversion has been added. I 
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20528 NAME 

20529 id — return user identity 

20530 SYNOPSIS 

20531 id [user] 

20532 id — G [—n] [user] 

20533 id — g [—nr] [user] 

20534 id — u[—nr] [user] 

20535 DESCRIPTION 

20536 If no user operand is provided, the id utility shall write the user and group IDs and the 

20537 corresponding user and group names of the invoking process to standard output. If the effective 

20538 and real IDs do not match, both shall be written. If multiple groups are supported by the 

20539 underlying system (see the description of |NGROUPS_MAX} in the System Interfaces volume of 

20540 IEEE Std. 1003.1-200x), the supplementary group affiliations of the invoking process shall also be 

20541 written. 

20542 If a user operand is provided and the process has the appropriate privileges, the user and group 

20543 IDs of the selected user shall be written. In this case, effective IDs shall be assumed to be 

20544 identical to real IDs. If the selected user has more than one allowable group membership listed 

20545 in the group database, these shall be written in the same manner as the supplementary groups 

20546 described in the preceding paragraph. 

20547 OPTIONS 

20548 The id utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

20549 Section 12.2, Utility Syntax Guidelines. I 

20550 The following options shall be supported: 

20551 -G Output all different group IDs (effective, real, and supplementary) only, using the 

20552 format "%u\n". If there is more than one distinct group affiliation, output each 

20553 such affiliation, using the format " %u", before the <newline> character is output. 

20554 -g Output only the effective group ID, using the format " %u\n ". 

20555 -n Output the name in the format %s instead of the numeric ID using the format %u. 

20556 -r Output the real ID instead of the effective ID. 

20557 -u Output only the effective user ID, using the format " %u \ n ". 

20558 OPERANDS 

20559 The following operand shall be supported: 

20560 user The login name for which information is to be written. 

20561 STDIN 

20562 Not used. 

20563 INPUT FILES 

20564 None. 

20565 ENVIRONMENT VARIABLES 

20566 The following environment variables shall affect the execution of id: 

20567 LANG Provide a default value for the internationalization variables that are unset or null. 

20568 If LANG is unset or null, the corresponding value from the implementation- 

20569 dependent default locale shall be used. If any of the internationalization variables 

20570 contains an invalid setting, the utility shall behave as if none of the variables had 
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20571 


been defined. 


20572 

20573 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


20574 

20575 

20576 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


20577 LC_MESSAGES 

20578 Determine the locale that should be used to affect the format and contents of 

20579 diagnostic messages written to standard error and informative messages written to 

20580 standard output. 

20581 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


20582 ASYNCHRONOUS EVENTS 

20583 Default. 


20584 STDOUT 

20585 The following formats shall be used when the LC_MESSAGES locale category specifies the 

20586 POSIX locale. In other locales, the strings uid, gid, enid, egid, and groups may be replaced with 

20587 more appropriate strings corresponding to the locale. 

20588 "uid=%u(%s) gid=%u (%s) \n", <real user ID>, <user-name>, 

20589 <real group ID>, <group-name> 

20590 If the effective and real user IDs do not match, the following shall be inserted immediately 

20591 before the ' \n' character in the previous format: 

20592 " euid=%u(%s)" 

20593 with the following arguments added at the end of the argument list: 

20594 "effective user ID", <effective user-name> 

20595 If the effective and real group IDs do not match, the following shall be inserted directly before 

20596 the ' \n' character in the format string (and after any addition resulting from the effective and 

20597 real user IDs not matching): 

20598 " egid=%u(%s)" 

20599 with the following arguments added at the end of the argument list: 

20600 <effective group-ID>, <effective group name> 

20601 If the process has supplementary group affiliations or the selected user is allowed to belong to 

20602 multiple groups, the first shall be added directly before the <newline> character in the format 

20603 String: 

20604 " groups=%u (%s ) " 

20605 with the following arguments added at the end of the argument list: 

20606 <supplementary group ID>, <supplementary group name> 

20607 and the necessary number of the following added after that for any remaining supplementary 

20608 group IDs: 

20609 ",%u(%s)" 

20610 and the necessary number of the following arguments added at the end of the argument list: 


Commands and Utilities, Issue 6 


543 



id 


Utilities 


20611 

20612 

20613 

20614 

20615 

20616 

20617 

20618 

20619 

20620 

20621 

20622 

20623 

20624 

20625 

20626 

20627 

20628 

20629 

20630 

20631 

20632 

20633 

20634 

20635 

20636 

20637 

20638 

20639 

20640 

20641 

20642 

20643 

20644 

20645 

20646 

20647 

20648 

20649 

20650 

20651 


<supplementary group ID>, <supplementary group name> 

If any of the user ID, group ID, effective user ID, effective group ID, or supplementary/multiple 
group IDs cannot be mapped by the system into printable user or group names, the 
corresponding (%s) and name argument is omitted from the corresponding format string. 

When any of the options are specified, the output format shall be as described in the OPTIONS 
section. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Output produced by the -G option and by the default case could potentially produce very long 
lines on systems that support large numbers of supplementary groups. (On systems with user 
and group IDs that are 32-bit integers and with group names with a maximum of 8 bytes per 
name, 93 supplementary groups plus distinct effective and real group and user IDs could 
theoretically overflow the 2048-byte |LINE_MAX} text file line limit on the default output case. 
It would take about 186 supplementary groups to overflow the 2048-byte barrier using id -G). 
This is not expected to be a problem in practice, but in cases where it is a concern, applications 
should consider using fold -s before postprocessing the output of id. 

EXAMPLES 

None. 

RATIONALE 

The functionality provided by the 4 BSD groups utility can be simulated using: 

id —Gn [ user ] 

The 4 BSD command groups was considered, but it was not included because it did not provide 
the functionality of the id utility of the SVID. Also, it was thought that it would be easier to 
modify id to provide the additional functionality necessary to systems with multiple groups 
than to invent another command. 

The options -u, -g, -n, and -r were added to ease the use of id with shell commands 
substitution. Without these options it is necessary to use some preprocessor such as sed to select 
the desired piece of information. Since output such as that produced by: 

id —u —n 

is frequently wanted, it seemed desirable to add the options. 
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20652 FUTURE DIRECTIONS 

20653 None. 

20654 SEE ALSO 

20655 fold, logname, who, the System Interfaces volume of IEEE Std. 1003.1-200x, getgid(), getgroups(), 

20656 getuidf) 

20657 CHANGE HISTORY 

20658 First released in Issue 2. 

20659 Issue 4 

20660 Aligned with the ISO/IEC 9945-2:1993 standard. 
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20661 NAME 

20662 iperm — remove an XSI message queue, semaphore set, or shared memory segment identifier 

20663 SYNOPSIS 


20664 XSI 

iperm [ —q msgid 

| —Q msgkey | 

—s semid | 

—S semkey | 

20665 

—m shmid | —M 

shmkey ] ... 




20666 


20667 DESCRIPTION 

20668 The iperm utility shall remove zero or more message queues, semaphore sets, or shared memory 

20669 segments. The interprocess communication facilities to be removed are specified by the options. 

20670 Only a user with appropriate privilege shall be allowed to remove an interprocess 

20671 communication facility that was not created by or owned by the user invoking iperm. 


20672 OPTIONS 

20673 The iperm facility supports the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

20674 Section 12.2, Utility Syntax Guidelines. I 

20675 The following options shall be supported: 


20676 -q msgid Remove the message queue identifier msgid from the system and destroy the 

20677 message queue and data structure associated with it. 


20678 

20679 

20680 


-m slimid Remove the shared memory identifier shmid from the system. The shared memory 
segment and data structure associated with it shall be destroyed after the last 
detach. 


20681 -s semid Remove the semaphore identifier semid from the system and destroy the set of 

20682 semaphores and data structure associated with it. 


20683 

20684 


-Q msgkey Remove the message queue identifier, created with key visgkey, from the system 
and destroy the message queue and data structure associated with it. 


20685 

20686 
20687 


-M shmkey Remove the shared memory identifier, created with key slimkey, from the system. 

The shared memory segment and data structure associated with it shall be 
destroyed after the last detach. 


20688 

20689 


-S semkey Remove the semaphore identifier, created with key semkey, from the system and 
destroy the set of semaphores and data structure associated with it. 


20690 OPERANDS 

20691 None. 


20692 STDIN 

20693 Not used. 


20694 INPUT FILES 

20695 None. 


20696 ENVIRONMENT VARIABLES 

20697 The following environment variables shall affect the execution of iperm: 


20698 

20699 

20700 

20701 

20702 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contain an invalid setting, the utility behaves as if none of the variables had been 
set. 


20703 

20704 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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20705 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

20706 characters (for example, single-byte as opposed to multi-byte characters in 

20707 arguments). 

20708 LC_MESSAGES 

20709 Determine the locale that should be used to affect the format and contents of 

20710 diagnostic messages written to standard error. 

20711 NLSPATH 

20712 Determine the location of message catalogs for the processing of LC_MESSAGES. 

20713 ASYNCHRONOUS EVENTS 

20714 Default. 

20715 STDOUT 

20716 Not used. 

20717 STDERR 

20718 Used only for diagnostic messages. 

20719 OUTPUT FILES 

20720 None. 

20721 EXTENDED DESCRIPTION 

20722 None. 

20723 EXIT STATUS 

20724 The following exit values shall be returned: 

20725 0 Successful completion. 

20726 >0 An error occurred. 

20727 CONSEQUENCES OF ERRORS 

20728 Default. 

20729 APPLICATION USAGE 

20730 None. 

20731 EXAMPLES 

20732 None. 

20733 RATIONALE 

20734 None. 

20735 FUTURE DIRECTIONS 

20736 None. 

20737 SEE ALSO 

20738 ipcs , the System Interfaces volume of IEEE Std. 1003.1-200x, msgctl ( ), semctl (), shmctl () 

20739 CHANGE HISTORY 

20740 First released in Issue 5. 
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20741 NAME 

20742 

ipcs — report XSI interprocess communication facilities status 

20743 SYNOPSIS 


20744 XSI 

ipcs [—qms][—a I —bcopt] 

20745 



20746 DESCRIPTION 

20747 The ipcs utility shall write information about active interprocess communication facilities. 

20748 

20749 

20750 

Without options, information shall be written in short format for message queues, shared 
memory segments, and semaphores sets that are currently active in the system. Otherwise, the 
information that is displayed is controlled by the options specified. 

20751 OPTIONS 

20752 The ipcs facility supports the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

20753 Section 12.2, Utility Syntax Guidelines. 

20754 

The ipcs utility accepts the following options: 

20755 

-q 

Write information about active message queues. 

20756 

-m 

Write information about active shared memory segments. 

20757 

-s 

Write information about active semaphores sets. 

20758 

20759 

20760 

If -q, -m, or -s are specified, only information about those facilities shall be written. If none of 
these three are specified, information about all three shall be written subject to the following 
options: 

20761 

-a 

Use all print options. (This is a shorthand notation for -b, -c, -o, -p, and -t.) 

20762 

20763 

20764 

-b 

Write information on maximum allowable size. (Maximum number of bytes in 
messages on queue for message queues, size of segments for shared memory, and 
number of semaphores in each set for semaphores.) 

20765 

-c 

Write creator's user name and group name; see below. 

20766 

20767 

20768 

-o 

Write information on outstanding usage. (Number of messages on queue and total 
number of bytes in messages on queue for message queues, and number of 
processes attached to shared memory segments.) 

20769 

20770 

20771 

20772 

-P 

Write process number information. (Process ID of last process to send a message 
and process ID of last process to receive a message on message queues, process ID 
of creating process, and process ID of last process to attach or detach on shared 
memory segments.) 

20773 

20774 

20775 

20776 

-t 

Write time information. (Time of the last control operation that changed the access 
permissions for all facilities, time of last msgsnd( ) and msgrcv( ) operations on 
message queues, time of last shmat( ) and shmdt( ) operations on shared memory, 
and time of last semop{) operation on semaphores.) 

20777 OPERANDS 

20778 None. 


20779 STDIN 

20780 

Not used. 
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20782 

20783 

20784 

20785 

20786 

20787 

20788 

20789 

20790 

20791 

20792 

20793 

20794 

20795 

20796 

20797 

20798 

20799 

20800 

20801 

20802 

20803 

20804 

20805 

20806 

20807 

20808 

20809 

20810 
20811 

20812 

20813 

20814 

20815 

20816 

20817 

20818 

20819 

20820 
20821 
20822 


Utilities 


ipcs 


INPUT FILES 

• The group database 

• The user database 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of ipcs: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contain an invalid setting, the utility behaves as if none of the variables had been 
set. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

TZ Determine the timezone for the time strings written by ipcs. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

An introductory line shall be written with the format: 

"IPC status from %s as of %s\n", <source>, <date> 

where <sonrce> indicates the source used to gather the statistics and <dcite> is the information 
that would be produced by the date command when invoked in the POSIX locale. 

The ipcs utility then shall create up to three reports depending upon the -q, -m, and -s options. 
The first report shall indicate the status of message queues, the second report shall indicate the 
status of shared memory segments, and the third report shall indicate the status of semaphore 
sets. 

If the corresponding facility is not installed or has not been used since the last reboot, then the 
report shall be written out in the format: 

"%s facility not in system.\n", <facility> 

where <facility> is Message Queue, Shared Memory, or Semaphore, as appropriate. If the facility has 
been installed and has been used since the last reboot, column headings separated by one or 
more spaces and followed by a <newline> shall be written as indicated below followed by the 
facility name written out using the format: 

"%s:\n", <facility> 

where <facility> is Message Queues, Shared Memory, or Semaphores, as appropriate. On the second 
and third reports the column headings need not be written if the last column headings written 
already provide column headings for all information in that report. 
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20823 

20824 

20825 

20826 

20827 

20828 

The column headings provided in the first column below and the meaning of the information in 
those columns shall be given in order below; the letters in parentheses indicate the options that 
shall cause the corresponding column to appear; "all" means that the column shall always 
appear. Each column is separated by one or more <space> characters. Note that these options 
only determine what information is provided for each report; they do not determine which 
reports are written. 

20829 

T 

(all) 

Type of facility: 

20830 



q Message queue. 

20831 



m Shared memory segment. 

20832 



s Semaphore. 

20833 



This field is a single character written using the format %c. 

20834 

20835 

ID 

(all) 

The identifier for the facility entry. This field shall be written using the format 
%d. 

20836 

20837 

KEY 

(all) 

The key used as an argument to msgget( ), semget( ), or shmget( ) to create the 
facility entry. 

20838 

20839 

20840 



Note: The key of a shared memory segment is changed to IPC_PRIVATE 

when the segment has been removed until all processes attached 
to the segment detach it. 

20841 



This field shall be written using the format 0x%x. 

20842 

20843 

MODE 

(all) 

The facility access modes and flags. The mode shall consist of 11 characters 
that are interpreted as follows. 

20844 



The first character shall be: 

20845 



S If a process is waiting on a msgsnd( ) operation. 

20846 



- If the above is not true. 

20847 



The second character shall be: 

20848 



R If a process is waiting on a msgrcv( ) operation. 

20849 

20850 



C or - If the associated shared memory segment is to be cleared when the 
first attach operation is executed. 

20851 



- If none of the above is true. 

20852 

20853 

20854 

20855 

20856 

20857 



The next nine characters shall be interpreted as three sets of three bits each. 
The first set refers to the owner's permissions; the next to permissions of 
others in the usergroup of the facility entry; and the last to all others. Within 
each set, the first character indicates permission to read, the second character 
indicates permission to write or alter the facility entry, and the last character is 
a minus sign ('-'). 

20858 



The permissions shall be indicated as follows: 

20859 



r If read permission is granted. 

20860 



zv If write permission is granted. 

20861 



a If alter permission is granted. 

20862 



- If the indicated permission is not granted. 
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20863 

20864 

20865 

20866 

20867 



The first character following the permissions specifies if there is an alternate 
or additional access control method associated with the facility. If there is no 
alternate or additional access control method associated with the facility, a 
single <space> character shall be written; otherwise, another printable 
character is written. 

20868 

20869 

20870 

20871 

OWNER 

(all) 

The user name of the owner of the facility entry. If the user name of the owner 
is found in the user database, at least the first eight column positions of the 
name shall be written using the format %s. Otherwise, the user ID of the 
owner shall be written using the format %d. 

20872 

20873 

20874 

20875 

GROUP 

(all) 

The group name of the owner of the facility entry. If the group name of the 
owner is found in the group database, at least the first eight column positions 
of the name shall be written using the format %s. Otherwise, the group ID of 
the owner shall be written using the format %d. 

20876 

The following nine columns shall be only written out for message queues: 

20877 

20878 

20879 

20880 

CREATOR (a,c) 

The user name of the creator of the facility entry. If the user name of the 
creator is found in the user database, at least the first eight column positions 
of the name shall be written using the format %s. Otherwise, the user ID of 
the creator shall be written using the format %d. 

20881 

20882 

20883 

20884 

CGROUP 

(a,c) 

The group name of the creator of the facility entry. If the group name of the 
creator is found in the group database, at least the first eight column positions 
of the name shall be written using the format %s. Otherwise, the group ID of 
the creator shall be written using the format %d. 

20885 

20886 

CBYTES 

(a,o) 

The number of bytes in messages currently outstanding on the associated 
message queue. This field shall be written using the format %d. 

20887 

20888 

QNUM 

(a,o) 

The number of messages currently outstanding on the associated message 
queue. This field shall be written using the format %d. 

20889 

20890 

QBYTES 

(a,b) 

The maximum number of bytes allowed in messages outstanding on the 
associated message queue. This field shall be written using the format %d. 

20891 

20892 

LSPID 

(a,p) 

The process ID of the last process to send a message to the associated queue. 
This field shall be written using the format: 

20893 



"%d", <pid> 

20894 

20895 

20896 



where <pid> is 0 if no message has been sent to the corresponding message 
queue; otherwise, <pid> shall be the process ID of the last process to send a 
message to the queue. 

20897 

20898 

LRPID 

(a,p) 

The process ID of the last process to receive a message from the associated 
queue. This field shall be written using the format: 

20899 



"%d", <pid> 

20900 

20901 

20902 



where <pid> is 0 if no message has been received from the corresponding 
message queue; otherwise, <pid> shall be the process ID of the last process to 
receive a message from the queue. 

20903 

20904 

20905 

20906 

STIME 

(a,t) 

The time the last message was sent to the associated queue. If a message has 
been sent to the corresponding message queue, the hour, minute, and second 
of the last time a message was sent to the queue shall be written using the 
format %d:%2.2d:%2.2d. Otherwise, the format " no-entry" shall be written. 
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20907 

20908 

20909 

20910 

20911 

RTIME 

(M) 

The time the last message was received from the associated queue. If a 
message has been received from the corresponding message queue, the hour, 
minute, and second of the last time a message was received from the queue 
shall be written using the format °/od:%2.2d:%2.2d. Otherwise, the format 
" no-entry " shall be written. 

20912 

The following eight columns shall be only written out for shared memory segments. 

20913 

20914 

20915 

20916 

CREATOR (a,c) 

The user of the creator of the facility entry. If the user name of the creator is 
found in the user database, at least the first eight column positions of the 
name shall be written using the format %s. Otherwise, the user ID of the 
creator shall be written using the format %d. 

20917 

20918 

20919 

20920 

CGROUP 

(a,c) 

The group name of the creator of the facility entry. If the group name of the 
creator is found in the group database, at least the first eight column positions 
of the name shall be written using the format %s. Otherwise, the group ID of 
the creator shall be written using the format %d. 

20921 

20922 

NATTCH 

(a,o) 

The number of processes attached to the associated shared memory segment. 
This field shall be written using the format %d. 

20923 

20924 

SEGSZ 

(a,b) 

The size of the associated shared memory segment. This field shall be written 
using the format %d. 

20925 

20926 

CPID 

(AP) 

The process ID of the creator of the shared memory entry. This field shall be 
written using the format %d. 

20927 

20928 

LPID 

(Ap) 

The process ID of the last process to attach or detach the shared memory 
segment. This field shall be written using the format: 

20929 



"%d", <pid> 

20930 

20931 

20932 



where <pid> is 0 if no process has attached the corresponding shared memory 
segment; otherwise, <pid> shall be the process ID of the last process to attach 
or detach the segment. 

20933 

20934 

20935 

20936 

20937 

ATIME 

(At) 

The time the last attach on the associated shared memory segment was 
completed. If the corresponding shared memory segment has ever been 
attached, the hour, minute, and second of the last time the segment was 
attached shall be written using the format %d:%2.2d:%2.2d. Otherwise, the 
format " no-entry" shall be written. 

20938 

20939 

20940 

20941 

20942 

DTIME 

(At) 

The time the last detach on the associated shared memory segment was 
completed. If the corresponding shared memory segment has ever been 
detached, the hour, minute, and second of the last time the segment was 
detached shall be written using the format °/od:%2.2d:%2.2d. Otherwise, the 
format " no-entry" shall be written. 

20943 

The following four columns shall be only written out for semaphore sets: 

20944 

20945 

20946 

20947 

CREATOR (a,c) 

The user of the creator of the facility entry. If the user name of the creator is 
found in the user database, at least the first eight column positions of the 
name shall be written using the format %s . Otherwise, the user ID of the 
creator shall be written using the format %d. 

20948 

20949 

20950 

20951 

CGROUP 

(AC) 

The group name of the creator of the facility entry. If the group name of the 
creator is found in the group database, at least the first eight column positions 
of the name shall be written using the format %s. Otherwise, the group ID of 
the creator shall be written using the format %d. 
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20952 

20953 


NSEMS (a,b) The number of semaphores in the set associated with the semaphore entry. I 
This field shall be written using the format %d. 


20954 

20955 

20956 

20957 

20958 

20959 


OTIME (a,t) The time the last semaphore operation on the set associated with the 
semaphore entry was completed. If a semaphore operation has ever been 
performed on the corresponding semaphore set, the hour, minute, and second 
of the last semaphore operation on the semaphore set shall be written using 
the format %d:%2.2d:%2.2d. Otherwise, the format " no-entry" shall be 
written. 


20960 The following column shall be written for all three reports when it is requested: 

20961 CTIME (a,t) The time the associated entry was created or changed. The hour, minute, and 

20962 second of the time when the associated entry was created shall be written 

20963 using the format %d:%2.2d:%2.2d. 

20964 STDERR 

20965 Used only for diagnostic messages. 

20966 OUTPUT FILES 

20967 None. 


20968 EXTENDED DESCRIPTION 

20969 None. 


20970 EXIT STATUS 

20971 The following exit values shall be returned: 

20972 0 Successful completion. 

20973 >0 An error occurred. 


20974 CONSEQUENCES OF ERRORS 

20975 Default. 


20976 APPLICATION USAGE 

20977 Things can change while ipcs is running; the information it gives is guaranteed to be accurate 

20978 only when it was retrieved. 

20979 EXAMPLES 

20980 None. 

20981 RATIONALE 

20982 None. 

20983 FUTURE DIRECTIONS 

20984 None. 

20985 SEE ALSO 

20986 The System Interfaces volume of IEEEStd. 1003.1-200x, msgop(), msgrcv (), msgsnd(), semget{), 

20987 semop(), shmat {), shmdt( ), shmget( ), shmop() 

20988 CHANGE HISTORY 

20989 First released in Issue 5. 


20990 Issue 6 

20991 The Open Group corrigenda item U020/1 has been applied, correcting the SYNOPSIS. 


20992 The Open Group corrigenda items U032/1 and U032/2 have been applied, clarifying the output 

20993 format. 
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The Open Group Base Resolution bwg98-004 is applied. 
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20995 NAME 

20996 jobs — display status of jobs in the current session 

20997 SYNOPSIS 

20998 UP jobs [-1 I —p] [job_id. . . ] 

20999 


21000 DESCRIPTION 

21001 The jobs utility shall display the status of jobs that were started in the current shell environment; 

21002 see Section 2.12 on page 90. 

21003 When jobs reports the termination status of a job, the shell shall remove its process ID from the 

21004 list of those "known in the current shell execution environment"; see Section 2.9.3.1 on page 74. 


21005 OPTIONS 

21006 The jobs utility shall conform to the System Interface Definitions volume of I 

21007 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

21008 The following options shall be supported: 


21009 -1 

21010 
21011 


(The letter ell.) Provide more information about each job listed. This information 
shall include the job number, current job, process group ID, state, and the 
command that formed the job. 


21012 


-p Display only the process IDs for the process group leaders of the selected jobs. 


21013 By default, the jobs utility shall display the status of all stopped jobs, running background jobs 

21014 and all jobs whose status has changed and have not been reported by the shell. 


21015 OPERANDS 

21016 The following operand shall be supported: 

21017 job_id Specifies the jobs for which the status is to be displayed. If no job_id is given, the 

21018 status information for all jobs shall be displayed. The format of job_id is described I 

21019 in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.207, I 

21020 Job Control Job ID. I 


21021 STDIN 

21022 Not used. 


21023 INPUT FILES 

21024 None. 


21025 ENVIRONMENT VARIABLES 

21026 The following environment variables shall affect the execution of jobs: 


21027 

21028 

21029 

21030 

21031 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


21032 

21033 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


21034 

21035 

21036 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


21037 LC_MESSAGES 

21038 Determine the locale that should be used to affect the format and contents of 
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21039 diagnostic messages written to standard error and informative messages written to 

21040 standard output. 

21041 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

21042 ASYNCHRONOUS EVENTS 

21043 Default. 


21044 STDOUT 

21045 If the -p option is specified, the output shall consist of one line for each process ID: 

21046 "%d\n", <process ID> 

21047 Otherwise, if the -1 option is not specified, the output shall be a series of lines of the form: 

21048 "[%d] %c %s %s\n", <job~number>, <current>, <state>, <command> 

21049 where the fields shall be as follows: 

21050 <current> The character ' +' identifies the job that would be used as a default for th efg or bg 

21051 utilities; this job can also be specified using th e job_id%+ or "%%". The character 

21052 ' identifies the job that would become the default if the current default job were 

21053 to exit; this job can also be specified using the job_id%-. For other jobs, this field is 

21054 a <space> character. At most one job can be identified with ' +' and at most one 

21055 job can be identified with ' - '. If there is any suspended job, then the current job 

21056 shall be a suspended job. If there are at least two suspended jobs, then the previous 

21057 job also shall be a suspended job. 

21058 <job-number> A number that can be used to identify the process group to the wait, fg, bg, and kill 

21059 utilities. Using these utilities, the job can be identified by prefixing the job number 

21060 with ' %'. 


21061 

21062 

21063 

21064 

21065 

21066 

21067 

21068 

21069 

21070 

21071 

21072 

21073 

21074 

21075 


<state> One of the following strings (in the POSIX locale): 

Running Indicates that the job has not been suspended by a signal and has not 
exited. 


Done 


Indicates that the job completed and returned exit status zero. 


Don e(code) Indicates that the job completed normally and that it exited with the 
specified non-zero exit status, code, expressed as a decimal number. 

Stopped Indicates that the job was suspended by the SIGTSTP signal. 

Stopped (SIGTSTP) 

Indicates that the job was suspended by the SIGTSTP signal. 

Stopped (SIGSTOP) 

Indicates that the job was suspended by the SIGSTOP signal. 

Stopped (SIGTTIN) 

Indicates that the job was suspended by the SIGTTIN signal. 

Stopped (SIGTTOU) 

Indicates that the job was suspended by the SIGTTOU signal. 


21076 The implementation may substitute the string Suspended in place of Stopped. If 

21077 the job was terminated by a signal, the format of <state> is unspecified, but it shall 

21078 be visibly distinct from all of the other <state> formats shown here and shall 

21079 indicate the name or description of the signal causing the termination. 
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21080 

21081 

21082 

21083 

21084 

21085 

21086 

21087 

21088 

21089 

21090 

21091 

21092 

21093 

21094 

21095 

21096 

21097 

21098 

21099 

21100 

21101 

21102 

21103 

21104 

21105 

21106 

21107 

21108 

21109 

21110 
21111 
21112 

21113 

21114 

21115 

21116 

21117 

21118 

21119 

21120 
21121 
21122 

21123 

21124 


<command> The associated command that was given to the shell. 

If the -1 option is specified, a field containing the process group ID shall be inserted before the 
<state> field. Also, more processes in a process group may be output on separate lines, using 
only the process ID and <command> fields. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The -p option is the only portable way to find out the process group of a job because different 
implementations have different strategies for defining the process group of the job. Usage such 
as $(jobs -p) provides a way of referring to the process group of the job in an implementation- 
independent way. 

The jobs utility does not work as expected when it is operating in its own utility execution 
environment because that environment has no applicable jobs to manipulate. See the 
APPLICATION USAGE section for bg on page 243. For this reason, jobs is generally 
implemented as a shell regular built-in. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

Both "%%" and "%+" are used to refer to the current job. Both forms are of equal validity—the 
"%%" mirroring "$$" and "%+" mirroring the output of jobs. Both forms reflect historical 
practice of the KomShell and the C shell with job control. 

The extensions to the shell specified in this volume of IEEE Std. 1003.1-200x have mostly been 
based on features provided by the KomShell. The job control features provided by bg,fg, and jobs 
are also based on the KomShell. The standard developers examined the characteristics of the C 
shell versions of these utilities and found that differences exist. Despite widespread use of the C 
shell, the KomShell versions were selected for this volume of IEEE Std. 1003.1-200x to maintain a 
degree of uniformity with the rest of the KomShell features selected (such as the very popular I 
command line editing features). I 

The jobs utility is not dependent on the job control option, as are the seemingly related bg and fg 
utilities because jobs is useful for examining background jobs, regardless of the condition of job 
control. When the user has invoked a set +m command and job control has been turned off, jobs 
can still be used to examine the background jobs associated with that current session. Similarly, 
kill can then be used to kill background jobs with kill% background job nnmber>. 
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21125 The output for terminated jobs is left unspecified to accommodate various historical systems. 

21126 The following formats have been witnessed: 

21127 1. Killed (signal name) 

21128 2. signal name 

21129 3. signal name (coredump) 

21130 4. signal description- core dumped 

21131 Most users should be able to understand these formats, although it means that applications have 

21132 trouble parsing them. 

21133 The calculation of job IDs was not described since this would suggest an implementation, which 

21134 may impose unnecessary restrictions. 

21135 In an early proposal, a -n option was included to "Display the status of jobs that have changed, 

21136 exited, or stopped since the last status report". It was removed because the shell always writes 

21137 any changed status of jobs before each prompt. 

21138 FUTURE DIRECTIONS 

21139 None. 

21140 SEE ALSO 

21141 bg , fg , kill , zvait 

21142 CHANGE HISTORY 

21143 First released in Issue 4. 

21144 Issue 6 

21145 This utility is now marked as part of the User Portability Utilities option. 

21146 The JC shading is removed as job control is mandatory in this issue. 
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21147 NAME 

21148 join — relational database operator 

21149 SYNOPSIS 

21150 join [—a file_number | —v file_number ] [—e string ] [—o list ] [—t char ] 

21151 [-1 field ] [-2 field ] filel file2 


21152 DESCRIPTION 

21153 The join utility shall perform an equality join on the tiles filel andfile2. The joined files shall be 

21154 written to the standard output. 

21155 The join field is a field in each file on which the files are compared. By default, join shall write 

21156 one line in the output for each pair of lines in filel and file! that have identical join fields. The 

21157 output line by default shall consist of the join field, then the remaining fields from filel , then the 

21158 remaining fields horn file!. This format can be changed by using the -o option (see below). The 

21159 -a option can be used to add unmatched lines to the output. The -v option can be used to output 

21160 only unmatched lines. 

21161 Notes to Reviewers 

21162 This section with side shading will not appear in the final copy. - Ed. 

21163 Dl, XCU, ERN 265 proposes to add the following text here: "If the same key appears more than 

21164 once in either file, all possible pairwise combinations are output, in unspecified order”. 

21165 By default, the files filel and filel should be ordered in the collating sequence of sort -b on the I 

21166 fields on which they shall be joined, by default the first in each line. All selected output shall be I 

21167 written in the same collating sequence. 

21168 The default input field separators shall be <blank> characters. In this case, multiple separators 

21169 shall count as one field separator, and leading separators shall be ignored. The default output 

21170 field separator shall be a <space> character. 

21171 The field separator and collating sequence can be changed by using the -t option (see below). 

21172 If the input files are not in the appropriate collating sequence, the results are unspecified. 


21173 OPTIONS 

21174 The join utility shall conform to the System Interface Definitions volume of I 

21175 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 


21176 The following options shall be supported: 


21177 

21178 

21179 

21180 


-a file_nnmber 

Produce a line for each unpairable line in file file_number , wher efile_number is 1 or 
2, in addition to the default output. If both -al and -a2 are specified, all unpairable 
lines shall be output. 


21181 


-e string Replace empty output fields in the list selected by -o with the string string. 


21182 -o list Construct the output line to comprise the fields specified in list, each element of 

21183 which shall have one of the following two forms: 


21184 

21185 


1. file_number.field, where file_number is a file number and field is a decimal 
integer field number 


21186 


2. 0 (zero), representing the join field 


21187 

21188 
21189 


The elements of list shall be either comma-separated or <blank>-separated, as I 
specified in Guideline 8 of the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. The fields specified I 
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21190 

21191 

21192 

21193 

21194 

21195 

21196 

21197 

21198 

21199 

21200 

21201 

21202 

21203 

21204 

21205 

21206 

21207 

21208 

21209 

21210 

21211 

21212 

21213 

21214 

21215 

21216 

21217 

21218 

21219 

21220 
21221 

21222 

21223 

21224 

21225 

21226 

21227 

21228 

21229 

21230 

21231 


j oin Utilities 


by list shall be written for all selected output lines. Fields selected by list that do I 
not appear in the input shall be treated as empty output fields. (See the -e option.) 
Only specifically requested fields shall be written. The application shall ensure that I 
list is a single command line argument. I 

-t char Use character char as a separator, for both input and output. Every appearance of 

char in a line shall be significant. When this option is specified, the collating 
sequence should be the same as sort without the -b option. 

-v file_nnmber 

Instead of the default output, produce a line only for each unpairable line in 
file_number , where file_number is 1 or 2. If both -vl and -v2 are specified, all 
unpairable lines shall be output. 

-1 field Join on the field th field of file 1. Fields are decimal integers starting with 1. 

-2 field Join on the field th field of file 2. Fields are decimal integers starting with 1. 

OPERANDS 

The following operands shall be supported: 
filel,filel 

A path name of a file to be joined. If either of th efilel or file! operands is ' —', the 
standard input shall be used in its place. 

STDIN 

The standard input shall be used only if th efilel or file! operand is . See the INPUT FILES 
section. 

INPUT FILES 

The input files shall be text files. I 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of join: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale of the collating sequence join expects to have been used when 
the input files were sorted. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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21232 

21233 

21234 

21235 

21236 

21237 

21238 

21239 

21240 

21241 

21242 

21243 

21244 

21245 

21246 

21247 

21248 

21249 

21250 

21251 

21252 

21253 

21254 

21255 

21256 

21257 

21258 

21259 

21260 
21261 

21262 

21263 

21264 

21265 

21266 

21267 

21268 

21269 

21270 

21271 

21272 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The join utility output shall be a concatenation of selected character fields. When the -o option 
is not specified, the output shall be: 

"%s%s%s\n", <join field>, <other filel fields>, 

<other file2 fields> 

If the join field is not the first field in a file, the <other file fields> for that file shall be: 

<fields preceding join field>, <fields following join field> 

When the -o option is specified, the output format shall be: 

"%s\n", <concatenation of fields> 

where the concatenation of fields is described by the -o option, above. 

For either format, each field (except the last) shall be written with its trailing separator character. 
If the separator is the default (<blank> characters), a single <space> character shall be written 
after each field (except the last). 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 All input files were output successfully. 

>0 An error occurred. 


CONSEQUENCES OF ERRORS 
Default. 


APPLICATION USAGE 

Path names consisting of numeric digits or of the form string.string should not be specified 
directly following the -o list. 

EXAMPLES 

The -o 0 field essentially selects the union of the join fields. For example, given file phone: 


! Name 

Don 

Hal 

Yasushi 


Phone Number 
+1 123-456-7890 
+1 234-567-8901 
+2 345-678-9012 


and file fax: 


! Name 
Don 
Keith 
Yasushi 


Fax Number 
+1 123-456-7899 
+1 456-789-0122 
+2 345-678-9011 
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21273 (where the large expanses of white space are meant to each represent a single <tab> character), 

21274 the command: 

21275 join —t "<tab>" —a 1 —a 2 —e ' (unknown)' —o 0,1.2,2.2 phone fax 

21276 would produce: 

21277 (Name Phone Number Fax Number 

21278 Don +1 123-456-7890 +1 123-456-7899 

21279 Hal +1 234-567-8901 (unknown) 

21280 Keith (unknown) +1 456-789-0122 

21281 Yasushi +2 345-678-9012 +2 345-678-9011 

21282 Notes to Reviewers 

21283 This section with side shading will not appear in the final copy. - Ed. 

21284 Dl, XCU, ERN 265 proposes to add the following example. 

21285 The following: 

21286 fa: 

21287 a x 

21288 a y 

21289 a z 

21290 f b: 

21291 a p 

21292 a q 

21293 would produce: 

21294 a x p 

21295 a x q 

21296 a y p 

21297 a y q 

21298 a z p 

21299 a z q 

21300 RATIONALE 

21301 The standard developers believed that join should operate as documented in the SVID and BSD 

21302 not as historically implemented. Most implementations do not parse the -o option as described 

21303 in their own documentation, and parse the elements as separate argv items until the item is not 

21304 of the form file_number.field . Early proposals indicated that undefined behavior would result if 

21305 numeric file names were used immediately following the obsolescent multiple-argument form 

21306 of the -o list. However, since join always requires two file name arguments, there never should 

21307 be any ambiguity about whether an argument is associated with -o or not, and this application 

21308 restriction is no longer present. 

21309 The -e option is only effective when used with -o because, unless specific fields are identified 

21310 using -o, join is not aware of what fields might be empty. The exception to this is the join field, 

21311 but identifying an empty join field with the -e string is not historical practice and some scripts 

21312 might break if this were changed. 

21313 The 0 field in the -o list was adopted from the Tenth Edition version of join to satisfy 

21314 international objections that the join in the base documents do not support the "full join" or 

21315 "outer join" described in relational database literature. Although it has been possible to include 

21316 a join field in the output (by default, or by field number using -o), the join field could not be 

21317 included for an unpaired line selected by -a. The -o 0 field essentially selects the union of the 
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21318 join fields. 

21319 This sort of outer join was not possible with the join commands in the base documents. The -o 0 

21320 field was chosen because it is an upward-compatible change for applications. An alternative was 

21321 considered: have the join field represent the union of the fields in the files (where they are 

21322 identical for matched lines, and one or both are null for unmatched lines). This was not adopted 

21323 because it would break some historical applications. 

21324 The obsolescent -j, -jl, and -]2 options have been removed in this draft. Early proposals 

21325 showed -\file_number field, but a space was never allowed before the file_nnmber and two I 

21326 option-arguments were never intended. I 

21327 The ability to specify file! as - is not historical practice; it was added for completeness. 

21328 The -v option is not historical practice, but was considered necessary because it permitted the 

21329 writing of only those lines that do not match on the join field, as opposed to the -a option, which 

21330 prints both lines that do and do not match. This additional facility is parallel with the -v option 

21331 of grey. 

21332 Some historical implementations have been encountered where a blank line in one of the input 

21333 files was considered to be the end of the file; the description in this volume of 

21334 IEEE Std. 1003.1-200x does not cite this as an allowable case. 

21335 FUTURE DIRECTIONS 

21336 None. 

21337 SEE ALSO 

21338 azvk, comm, sort, nniq 

21339 CHANGE HISTORY 

21340 First released in Issue 2. 

21341 Issue 4 

21342 Aligned with the ISO/IEC 9945-2:1993 standard. 

21343 Issue 6 

21344 The obsolescent -j options and the multi-argument -o option are withdrawn in this issue. I 

21345 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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21346 NAME 

21347 kill — terminate or signal processes 

21348 SYNOPSIS 

21349 kill — s signal_name pid. . . 


21350 kill —1 [exit_status] 


21351 DESCRIPTION 

21352 The kill utility shall send a signal to the process or processes specified by each pid operand. 

21353 For each pid operand, the kill utility shall perform actions equivalent to the kill() function 

21354 defined in the System Interfaces volume of IEEE Std. 1003.1-200x called with the following 

21355 arguments: 

21356 • The value of the pid operand shall be used as the pid argument. 

21357 • The sig argument is the value specified by the -s option, -signal_nnmber option, or the 

21358 -signal_name option, or by SIGTERM, if none of these options is specified. 


21359 OPTIONS 

21360 The kill utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

21361 Section 12.2, Utility Syntax Guidelines. I 

21362 The following options shall be supported: 

21363 -1 (The letter ell.) Write all values of signal_name supported by the implementation, if 

21364 no operand is given. If an exit_status operand is given and it is a value of the ' ?' 

21365 shell special parameter (see Section 2.5.2 on page 43 and wait on page 1084) 

21366 corresponding to a process that was terminated by a signal, the signal_name 

21367 corresponding to the signal that terminated the process shall be written. If an 

21368 exit_statns operand is given and it is the unsigned decimal integer value of a signal 

21369 number, the signal_name (the symbolic constant name without the SIG prefix 

21370 defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x) 

21371 corresponding to that signal shall be written. Otherwise, the results are 

21372 unspecified. 


21373 -s signal_name 

21374 Specify the signal to send, using one of the symbolic names defined in the 

21375 <signal.h> header defined in the System Interface Definitions volume of I 

21376 IEEE Std. 1003.1-200x, Chapter 13, Headers. Values of signal_name shall be I 

21377 recognized in a case-independent fashion, without the SIG prefix. In addition, the 

21378 symbolic name 0 shall be recognized, representing the signal value zero. The 

21379 corresponding signal shall be sent instead of SIGTERM. 


21380 OPERANDS 

21381 The following operands shall be supported: 


21382 


One of the following: 


21383 

21384 

21385 

21386 

21387 

21388 

21389 

21390 


1. A decimal integer specifying a process or process group to be signaled. The 
process or processes selected by positive, negative and zero values of the pid 
operand shall be as described for the kill () function defined in the System 
Interfaces volume of IEEE Std. 1003.1-200x. If process number 0 is specified, 
all processes in the current process group are signaled. For the effects of 
negative pid numbers, see the kill () function defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x. If the first pid operand is negative, it should 
be preceded by "—" to keep it from being interpreted as an option. 
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21391 

21392 

21393 

21394 

21395 

21396 exit_status 

21397 


21398 STDIN 

21399 Not used. 


2. A job control job ID (see the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 3.207, Job Control Job ID) that identifies a I 
background process group to be signaled. The job control job ID notation is I 
applicable only for invocations of kill in the current shell execution 
environment; see Section 2.12 on page 90. 

A decimal integer specifying a signal number or the exit status of a process 
terminated by a signal. 


21400 INPUT FILES 

21401 None. 


21402 ENVIRONMENT VARIABLES 

21403 The following environment variables shall affect the execution of kill: 


21404 

21405 

21406 

21407 

21408 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


21409 

21410 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


21411 

21412 

21413 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


21414 LC_MESSAGES 

21415 Determine the locale that should be used to affect the format and contents of 

21416 diagnostic messages written to standard error. 

21417 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


21418 ASYNCHRONOUS EVENTS 

21419 Default. 


21420 STDOUT 

21421 When the -1 option is not specified, the standard output shall not be used. 

21422 When the -1 option is specified, the symbolic name of each signal shall be written in the 

21423 following format: 

21424 "%s%c", <signal_name>, <separator> 

21425 where the <signal_name> is in uppercase, without the SIG prefix, and the <separator> shall be 

21426 either a <newline> character or a <space> character. For the last signal written, <sepamtor> shall 

21427 be a <newline> character. 

21428 When both the -1 option and exit_status operand are specified, the symbolic name of the 

21429 corresponding signal shall be written in the following format: 

21430 "%s\n", <signal_name> 
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21431 STDERR 

21432 Used only for diagnostic messages. 

21433 OUTPUT FILES 

21434 None. 

21435 EXTENDED DESCRIPTION 

21436 None. 

21437 EXIT STATUS 

21438 The following exit values shall be returned: 

21439 0 At least one matching process was found for each pid operand, and the specified signal was 

21440 successfully processed for at least one matching process. 

21441 >0 An error occurred. 

21442 CONSEQUENCES OF ERRORS 

21443 Default. 

21444 APPLICATION USAGE 

21445 Process numbers can be found by using ps. 

21446 The job control job ID notation is not required to work as expected when kill is operating in its 

21447 own utility execution environment. In either of the following examples: 

21448 nohup kill %1 & 

21449 system ("kill %1"); 

21450 the kill operates in a different environment and does not share the shell's understanding of job 

21451 numbers. 

21452 EXAMPLES 

21453 Any of the commands: 

21454 kill -s kill 100 -165 

21455 kill -s KILL 100 -165 

21456 sends the SIGKILL signal to the process whose process ID is 100 and to all processes whose 

21457 process group ID is 165, assuming the sending process has permission to send that signal to the 

21458 specified processes, and that they exist. 

21459 The System Interfaces volume of IEEE Std. 1003.1-200x and this volume of IEEE Std. 1003.1-200x 

21460 do not require specific signal numbers for any signal_names . Even the -signal_nnmber option 

21461 provides symbolic (although numeric) names for signals. If a process is terminated by a signal, 

21462 its exit status indicates the signal that killed it, but the exact values are not specified. The kill -1 

21463 option, however, can be used to map decimal signal numbers and exit status values into the 

21464 name of a signal. The following example reports the status of a terminated job: 

21465 job 

21466 stat=$ ? 

21467 if [ $stat —eq 0 ] 

21468 then 

21469 echo job completed successfully. 

21470 elif [ $stat — gt 128 ] 

21471 then 

21472 echo job terminated by signal SIG$ (kill —1 $stat) . 

21473 else 

21474 echo job terminated with error code $stat. 

21475 fi 
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21477 
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21514 
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21517 


To avoid an ambiguity of an initial negative number argument specifying either a signal number 
or a process group, the ISO/IEC 9945-2:1993 standard mandates that it always be considered the 
former. Therefore, to send the default signal to a process group (say 123), an application should 
use a command similar to one of the following: 

kill -TERM -123 
kill-123 

RATIONALE 

The -1 option originated from the C shell, and is also implemented in the KomShell. The C shell 
output can consist of multiple output lines because the signal names do not always fit on a 
single line on some terminal screens. The KomShell output also included the implementation- 
dependent signal numbers and was considered by the standard developers to be too difficult for 
scripts to parse conveniently. The specified output format is intended not only to accommodate 
the historical C shell output, but also to permit an entirely vertical or entirely horizontal listing 
on systems for which this is appropriate. 

An early proposal invented the name SIGNULL as a signal_name for signal 0 (used by the System 
Interfaces volume of IEEE Std. 1003.1-200x to test for the existence of a process without sending 
it a signal). Since the signal_name 0 can be used in this case unambiguously, SIGNULL has been 
removed. 

An early proposal also required symbolic signal_name s to be recognized with or without the SIG 
prefix. Historical versions of kill have not written the SIG prefix for the -1 option and have not 
recognized the SIG prefix on signal_name s. Since neither application portability nor ease-of-use 
would be improved by requiring this extension, it is no longer required. 

This volume of IEEE Std. 1003.1-200x contains no utility that browses for process IDs. Values for 
pid are available via the ' !' and ' $' parameters of the shell command language. 

The -s option was added in response to international interest in providing some form of kill that 
meets the Utility Syntax Guidelines. 

The job control job ID notation is not required to work as expected when kill is operating in its 
own utility execution environment. In either of the following examples: 

nohup kill %1 & 
system("kill %1"); 

the kill operates in a different environment and does not understand how the shell has managed 
its job numbers. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

ps, wait, the System Interfaces volume of IEEE Std. 1003.1-200x, kill (), <signal.h> 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

The obsolescent versions of the SYNOPSIS are withdrawn in this issue. 
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lex 


NAME 

lex — generate programs for lexical tasks (DEVELOPMENT) 

SYNOPSIS 

CD lex —c [—■t] [—n| —v] [file ...] 

DESCRIPTION 

The lex utility shall generate C programs to be used in lexical processing of character input, and 
that can be used as an interface to yacc. The C programs shall be generated from lex source code 
and conform to the ISO C standard. Usually, the lex utility shall write the program it generates to 
the file lex.yy.c; the state of this file is unspecified if lex exits with a non-zero exit status. See the 
EXTENDED DESCRIPTION section for a complete description of the lex input language. 

OPTIONS 

The lex utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-n Suppress the summary of statistics usually written with the -v option. If no table 

sizes are specified in the lex source code and the -v option is not specified, then -n 
is implied. 

-t Write the resulting program to standard output instead of lex.yy.c. 

-v Write a summary of lex statistics to the standard output. (See the discussion of lex 

table sizes in Definitions in lex on page 570.) If the -t option is specified and -n is 
not specified, this report shall be written to standard error. If table sizes are 
specified in the lex source code, and if the -n option is not specified, the -v option 
may be enabled. 

OPERANDS 

The following operand shall be supported: 

file A path name of an input file. If more than one such file is specified, all files shall be 

concatenated to produce a single lex program. If no file operands are specified, or if 
a file operand is ' , the standard input shall be used. 

STDIN 

The standard input shall be used if no file operands are specified, or if a file operand is ' - '. See 
INPUT FILES. 

INPUT FILES 

The input files shall be text files containing lex source code, as described in the EXTENDED I 
DESCRIPTION section. 

ENVIRONMENT VARIABLES 

If this variable is not set to the POSIX locale, the results are unspecified. 

The following environment variables shall affect the execution of lex: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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21563 LC_COLLATE 

21564 Determine the locale for the behavior of ranges, equivalence classes and multi- 

21565 character collating elements within regular expressions. If this variable is not set to 

21566 the POSIX locale, the results are unspecified. 

21567 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

21568 characters (for example, single-byte as opposed to multi-byte characters in 

21569 arguments and input files), and the behavior of character classes within regular 

21570 expressions. If this variable is not set to the POSIX locale, the results are 

21571 unspecified. 

21572 ECJAESSAGES 

21573 Determine the locale that should be used to affect the format and contents of 

21574 diagnostic messages written to standard error. 

21575 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


21576 ASYNCHRONOUS EVENTS 

21577 Default. 


21578 STDOUT 

21579 If the -t option is specified, the text file of C source code output of lex shall be written to 

21580 standard output. 

21581 If the -t option is not specified: 

21582 • Implementation-dependent informational, error, and warning messages concerning the 

21583 contents of lex source code input shall be written to either the standard output or standard 

21584 error. 


21585 • If the -v option is specified and the -n option is not specified, lex statistics shall also be 

21586 written to either the standard output or standard error, in an implementation-dependent 

21587 format. These statistics may also be generated if table sizes are specified with a ' %' operator 

21588 in the Definitions section, as long as the -n option is not specified. 


21589 STDERR 

21590 If the -t option is specified, implementation-dependent informational, error, and warning 

21591 messages concerning the contents of lex source code input shall be written to the standard error. 

21592 If the -t option is not specified: 

21593 1. Implementation-dependent informational, error, and warning messages concerning the 

21594 contents of lex source code input shall be written to either the standard output or standard 

21595 error. 


21596 

21597 

21598 

21599 


2. If the -v option is specified and the -n option is not specified, lex statistics shall also be 
written to either the standard output or standard error, in an implementation-dependent 
format. These statistics may also be generated if table sizes are specified with a ' %' 
operator in the Definitions section, as long as the -n option is not specified. 


21600 OUTPUT FILES 

21601 A text file containing C source code shall be written to lex.yy.c, or to the standard output if the 

21602 -t option is present. 


21603 EXTENDED DESCRIPTION 

21604 Each input file contains lex source code, which is a table of regular expressions with 

21605 corresponding actions in the form of C program fragments. 

21606 When lex.yy.c is compiled and linked with the lex library (using the -11 operand with c89 or cc), 

21607 the resulting program reads character input from the standard input and partitions it into strings 
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that match the given expressions. 

When an expression is matched, these actions shall occur: 

• The input string that was matched is left in yytext as a null-terminated string; yytext is either 
an external character array or a pointer to a character string. As explained in Definitions in 
lex, the type can be explicitly selected using the %array or %pointer declarations, but the 
default is implementation-dependent. 

• The external int yyleng is set to the length of the matching string. 

• The expression's corresponding program fragment, or action, is executed. 

During pattern matching, lex shall search the set of patterns for the single longest possible 
match. Among rules that match the same number of characters, the rule given first shall be 
chosen. 

The general format of lex source shall be: 

Definitions 

O/ O/ 

/o /o 

Rules 

o/ O/ 

/o /o 

LlserSubroutines 

The first "%%" is required to mark the beginning of the rules (regular expressions and actions); 
the second " %% " is required only if user subroutines follow. 

Any line in the Definitions section beginning with a <blank> character shall be assumed to be a C 
program fragment and shall be copied to the external definition area of the lex.yy.c file. 
Similarly, anything in the Definitions section included between delimiter lines containing only 
" % {" and " %}" shall also be copied unchanged to the external definition area of the lex.yy.c file. 

Any such input (beginning with a <blank> character or within " % { " and " % } " delimiter lines) 
appearing at the beginning of the Rules section before any rules are specified shall be written to 
lex.yy.c after the declarations of variables for the yylex function and before the first line of code 
in yylex . Thus, user variables local to yylex can be declared here, as well as application code to 
execute upon entry to yylex. 

The action taken by lex when encountering any input beginning with a <blank> character or 
within " % {" and " %}" delimiter lines appearing in the Rules section but coming after one or 
more rules is undefined. The presence of such input may result in an erroneous definition of the 
yylex function. 

Definitions in lex 

Definitions appear before the first " %%" delimiter. Any line in this section not contained between 
" % {" and " %}" lines and not beginning with a <blank> character shall be assumed to define a 
lex substitution string. The format of these lines shall be: 

name substitute 

If a name does not meet the requirements for identifiers in the ISO C standard, the result is 
undefined. The string substitute shall replace the string {name} when it is used in a rule. The name 
string shall be recognized in this context only when the braces are provided and when it does 
not appear within a bracket expression or within double-quotes. 

In the Definitions section, any line beginning with a ' %' (percent sign) character and followed by 
an alphanumeric word beginning with either 's' or ' S' shall define a set of start conditions. 
Any line beginning with a ' %' followed by a word beginning with either ' x' or ' X ' shall define 
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a set of exclusive start conditions. When the generated scanner is in a " % s " state, patterns with 
no state specified shall be also active; in a "%x" state, such patterns shall not be active. The rest 
of the line, after the first word, shall be considered to be one or more <blank> character- 
separated names of start conditions. Start condition names shall be constructed in the same way 
as definition names. Start conditions can be used to restrict the matching of regular expressions 
to one or more states as described in Regular Expressions in lex on page 572. 

Implementations shall accept either of the following two mutually exclusive declarations in the 
Definitions section: 

% array Declare the type of yytext to be a null-terminated character array. 

%pointer Declare the type of yytext to be a pointer to a null-terminated character string. 

The default type of yytext is implementation-dependent. If an application refers to yytext outside 
of the scanner source file (that is, via an extern), the application shall include the appropriate 
%array or %pointer declaration in the scanner source file. 

Implementations shall accept declarations in the Definitions section for setting certain internal 
table sizes. The declarations are shown in the following table. 

Table 4-9 Table Size Declarations in lex 


Declaration 

Description 

Minimum Value 

%p n 

Number of positions 

2 500 

%n n 

Number of states 

500 

%a n 

Number of transitions 

2 000 

%e n 

Number of parse tree nodes 

1000 

%k n 

Number of packed character classes 

1000 

%o n 

Size of the output array 

3000 


In the table, n represents a positive decimal integer, preceded by one or more <blank> 
characters. The exact meaning of these table size numbers is implementation-dependent. The 
implementation shall document how these numbers affect the lex utility and how they are 
related to any output that may be generated by the implementation should space limitations be 
encountered during the execution of lex. It shall be possible to determine from this output which 
of the table size values needs to be modified to permit lex to successfully generate tables for the 
input language. The values in the column Minimum Value represent the lowest values 
conforming implementations shall provide. 

Rules in lex 

The rules in lex source files are a table in which the left column contains regular expressions and 
the right column contains actions (C program fragments) to be executed when the expressions 
are recognized. 

ERE action 
ERE action 

The extended regular expression (ERE) portion of a row shall be separated from action by one or 
more <blank> characters. A regular expression containing <blank> characters shall be 
recognized under one of the following conditions: 

• The entire expression appears within double-quotes. 

• The <blank> characters appear within double-quotes or square brackets. 
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• Each <blank> character is preceded by a backslash character. 

User Subroutines in lex 

Anything in the user subroutines section shall be copied to lex.yy.c following yylex. 

Regular Expressions in lex 

The lex utility shall support the set of extended regular expressions (see the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 9.4, Extended Regular Expressions), with I 
the following additions and exceptions to the syntax: I 

Any string enclosed in double-quotes shall represent the characters within the 
double-quotes as themselves, except that backslash escapes (which appear in the 
following table) shall be recognized. Any backslash-escape sequence shall be 
terminated by the closing quote. For example, " \ 01"" 1" represents a single 
string: the octal value 1 followed by the character ' 1'. 

<state>r, <statel,state2,.. >r 

The regular expression r shall be matched only when the program is in one of the 
start conditions indicated by state, statel, and so on; see Actions in lex on page 574. 
(As an exception to the typographical conventions of the rest of this volume of 
IEEE Std. 1003.1-200x, in this case <state> does not represent a metavariable, but 
the literal angle-bracket characters surrounding a symbol.) The start condition 
shall be recognized as such only at the beginning of a regular expression. 

r/x The regular expression r shall be matched only if it is followed by an occurrence of 

regular expression x (x is the instance of trailing context, further defined below). 
The token returned in yytext shall only match r. If the trailing portion of r matches 
the beginning of x, the result is unspecified. The r expression cannot include 
further trailing context or the ' $' (match-end-of-line) operator; x cannot include 
the ' '' (match-beginning-of-line) operator, nor trailing context, nor the ' $' 
operator. That is, only one occurrence of trailing context is allowed in a lex regular 
expression, and the ' '' operator only can be used at the beginning of such an 
expression. 

{name} When name is one of the substitution symbols from the Definitions section, the 

string, including the enclosing braces, shall be replaced by the substitute value. The 
substitute value shall be treated in the extended regular expression as if it were 
enclosed in parentheses. No substitution shall occur if {name} occurs within a 
bracket expression or within double-quotes. 

Within an ERE, a backslash character shall be considered to begin an escape sequence as I 
specified in the table in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 5, File Format Notation ('W, '\a', ' \b', '\f', '\n', '\r', ' \t', '\v'). In I 
addition, the escape sequences in the following table shall be recognized. 

A literal <newline> character cannot occur within an ERE; the escape sequence ' \n' can be 
used to represent a <newline> character. A <newline> character shall not be matched by a 
period operator. 
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Table 4-10 Escape Sequences in lex 


Escape 

Sequence 

Description 

Meaning 

\digits 

A backslash character followed 
by the longest sequence of one, 
two, or three octal-digit 
characters (01234567). If all of 
the digits are 0, (that is, 
representation of the NUL 
character), the behavior is 
undefined. 

The character whose encoding is 
represented by the one, two, or 
three-digit octal integer. If the 
size of a byte on the system is 
greater than nine bits, the valid 
escape sequence used to 
represent a byte is 
implementation-dependent. 
Multi-byte characters require 
multiple, concatenated escape 
sequences of this type, including 
the leading ' \' for each byte. 

\xdigits 

A backslash character followed 
by the longest sequence of 
hexadecimal-digit characters 
(01234567abcdefABCDEF). If all 
of the digits are 0, (that is, 
representation of the NUL 
character), the behavior is 
undefined. 

The character whose encoding is 
represented by the hexadecimal 
integer. 

\c 

A backslash character followed 
by any character not described 
in this table or in the table in the 
System Interface Definitions 
volume of 

IEEE Std. 1003.1-200x, Chapter 

5, File Format Notation (' \ \', 

'\a','\b',' \f', '\n','\r', 

' \t', ' \v'). 

The character ' c', unchanged. 


The order of precedence given to extended regular expressions for lex differs from that specified I 
in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.4, Extended I 
Regular Expressions. The order of precedence for lex shall be as shown in the following table, I 
from high to low. 

Note: The escaped characters entry is not meant to imply that these are operators, but they 

are included in the table to show their relationships to the true operators. The start 
condition, trailing context, and anchoring notations have been omitted from the table 
because of the placement restrictions described in this section; they can only appear 
at the beginning or ending of an ERE. 
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Table 4-11 ERE Precedence in lex 


Extended Regular Expression 

Precedence 

collation-related bracket symbols 

[= =] [: :] [• •] 

escaped characters 

\<special character> 

bracket expression 

[ ] 

quoting 

If II 

grouping 

( ) 

definition 

{ name } 

single-character RE duplication 
concatenation 

* + ? 

interval expression 
alternation 

{m, n} 

1 


The ERE anchoring operators ' "' and ' $') do not appear in the table. With lex regular 
expressions, these operators are restricted in their use: the ' '' operator can only be used at the 
beginning of an entire regular expression, and the ' $' operator only at the end. The operators 
apply to the entire regular expression. Thus, for example, the pattern " ("abc) I (def$) " is 
undefined; it can instead be written as two separate rules, one with the regular expression 
"" abc" and one with "def$", which share a common action via the special ' \ ' action (see 
below). If the pattern were written " "abc | def $", it would match either "abc" or "def" on a 
line by itself. 

Unlike the general ERE rules, embedded anchoring is not allowed by most historical lex 
implementations. An example of embedded anchoring would be for patterns such as 
" (" | ) foo ( | $) " to match " foo" when it exists as a complete word. This functionality can 
be obtained using existing lex features: 

A foo/ [ \n] | 

" foo"/[ \n] /* Found foo as a separate word. */ 

Note also that ' $' is a form of trailing context (it is equivalent to " / \ n ") and as such cannot be 
used with regular expressions containing another instance of the operator (see the preceding 
discussion of trailing context). 

The additional regular expressions trailing-context operator ' /' can be used as an ordinary 
character if presented within double-quotes, preceded by a backslash, or within a 

bracket expression, " [ / ] ". The start-condition ' <' and ' >' operators shall be special only in a 
start condition at the beginning of a regular expression; elsewhere in the regular expression they 
shall be treated as ordinary characters. 

Actions in lex 

The action to be taken when an ERE is matched can be a C program fragment or the special 
actions described below; the program fragment can contain one or more C statements, and can 
also include special actions. The empty C statement ' ;' shall be a valid action; any string in the 
lex.yy.c input that matches the pattern portion of such a rule is effectively ignored or skipped. 
However, the absence of an action shall not be valid, and the action lex takes in such a condition 
is undefined. 

The specification for an action, including C statements and special actions, can extend across 
several lines if enclosed in braces: 

ERE <one or more blanks> { program statement 

program statement } 
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21821 

21822 

21823 

21824 
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21826 
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The default action when a string in the input to a lex.yy.c program is not matched by any 
expression shall be to copy the string to the output. Because the default behavior of a program 
generated by lex is to read the input and copy it to the output, a minimal lex source program that 
has just " %% " shall generate a C program that simply copies the input to the output unchanged. 

Four special actions shall be available: 

I ECHO; REJECT; BEGIN 

| The action ' | ' means that the action for the next rule is the action for this rule. 

Unlike the other three actions, ' | ' cannot be enclosed in braces or be semicolon- I 
terminated; the application shall ensure that it is specified alone, with no other I 
actions. I 

ECHO; Write the contents of the string yytext on the output. 

REJECT; Usually only a single expression is matched by a given string in the input. REJECT 
means "continue to the next expression that matches the current input", and shall 
cause whatever rule was the second choice after the current rule to be executed for 
the same input. Thus, multiple rules can be matched and executed for one input 
string or overlapping input strings. For example, given the regular expressions 
" xy z " and " xy " and the input " xy z ", usually only the regular expression " xy z " 
would match. The next attempted match would start after z. If the last action in the 
"xyz" rule is REJECT, both this rule and the "xy" rule would be executed. The 
REJECT action may be implemented in such a fashion that flow of control does not 
continue after it, as if it were equivalent to a goto to another part of yylex . The use 
of REJECT may result in somewhat larger and slower scanners. 

BEGIN The action: 

BEGIN newstate; 

switches the state (start condition) to newstate. If the string newstate has not been 
declared previously as a start condition in the Definitions section, the results are 
unspecified. The initial state is indicated by the digit ' 0' or the token INITIAL. 

The functions or macros described below are accessible to user code included in the lex input. It 
is unspecified whether they appear in the C code output of lex, or are accessible only through the 
-11 operand to c89 or cc (the lex library). 

int yylex(v oid) 

Performs lexical analysis on the input; this is the primary function generated by the lex 
utility. The function shall return zero when the end of input is reached; otherwise, it shall 
return non-zero values (tokens) determined by the actions that are selected. 

int yymoretyoid) 

When called, indicates that when the next input string is recognized, it is to be appended to 
the current value of yytext rather than replacing it; the value in yyleng shall be adjusted 
accordingly. 

int yyless( int n) 

Retains n initial characters in yytext, NUL-terminated, and treats the remaining characters 
as if they had not been read; the value in yyleng shall be adjusted accordingly. 

int input(void) 

Returns the next character from the input, or zero on end-of-file. It shall obtain input from 
the stream pointer yyin , although possibly via an intermediate buffer. Thus, once scanning 
has begun, the effect of altering the value of yyin is undefined. The character read is 
removed from the input stream of the scanner without any processing by the scanner. 
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21867 int unput( int c) 

21868 Returns the character ' c' to the input; yytext and yyleng are undefined until the next 

21869 expression is matched. The result of using unput for more characters than have been input is 

21870 unspecified. 

21871 The following functions appear only in the lex library accessible through the -11 operand; they 

21872 can therefore be redefined by a portable application: 

21873 int yywrap (void) 

21874 Called by yylex at end-of-file; the default yyzvrap always shall return 1. If the application 

21875 requires yylex to continue processing with another source of input, then the application can 

21876 include a function yyzvrap, which associates another file with the external variable FILE *yyin 

21877 and shall return a value of zero. 

21878 int main( int urge, char *argv[ ]) 

21879 Calls yylex to perform lexical analysis, then exits. The user code can contain main to perform 

21880 application-specific operations, calling yylex as applicable. 

21881 Except for input, iinpnt, and main, all external and static names generated by lex shall begin with 

21882 the prefix yy or YY. 

21883 EXIT STATUS 

21884 The following exit values shall be returned: 

21885 0 Successful completion. 

21886 >0 An error occurred. 

21887 CONSEQUENCES OF ERRORS 

21888 Default. 

21889 APPLICATION USAGE 

21890 Portable applications are warned that in the Rules section, an ERE without an action is not 

21891 acceptable, but need not be detected as erroneous by lex. This may result in compilation or I 

21892 runtime errors. I 

21893 The purpose of input is to take characters off the input stream and discard them as far as the 

21894 lexical analysis is concerned. A common use is to discard the body of a comment once the 

21895 beginning of a comment is recognized. 

21896 The lex utility is not fully internationalized in its treatment of regular expressions in the lex 

21897 source code or generated lexical analyzer. It would seem desirable to have the lexical analyzer 

21898 interpret the regular expressions given in the lex source according to the environment specified 

21899 when the lexical analyzer is executed, but this is not possible with the current lex technology. 

21900 Furthermore, the very nature of the lexical analyzers produced by lex must be closely tied to the 

21901 lexical requirements of the input language being described, which is frequently locale-specific 

21902 anyway. (For example, writing an analyzer that is used for French text is not automatically 

21903 useful for processing other languages.) 

21904 EXAMPLES 

21905 The following is an example of a lex program that implements a rudimentary scanner for a 

21906 Pascal-like syntax: 

21907 % { 

21908 /* Need this for the call to atof() below. */ 

21909 #include <math.h> 

21910 /* Need this for printf(), fopen(), and stdin below. */ 

21911 #include <stdio.h> 

21912 %} 


576 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


lex 


21913 

21914 
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21917 
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21938 
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21944 

21945 

21946 

21947 
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DIGIT [0-9] 

ID [a-z][a-zO-9]* 


{DIGIT}+ { 

printf("An integer: %s (%d)\n", yytext, 
atoi(yytext)); 

} 

{DIGITJ+"{DIGIT}* { 

printf("A float: %s (%g)\n", yytext, 
atof (yytext)); 

} 

if|then|begin|end|procedure|function { 

printf("A keyword: %s\n", yytext); 

} 

{ID} printf("An identifier: %s\n", yytext); 

|||printf("An operator: %s\n", yytext); 

"{"['}\n]*"}" /* Eat up one-line comments. */ 

[ \t\n]+ /* Eat up white space. */ 

printf("Unrecognized character: %s\n", yytext); 

"6 "6 

int main(int argc, char *argv[]) 

{ 

++argv, —argc; /* Skip over program name. */ 

if (argc > 0) 

yyin = fopen(argv[0], "r"); 

else 

yyin = stdin; 
yylex() ; 

} 

RATIONALE 

Even though the -c option and references to the C language are retained in this description, lex 
may be generalized to other languages, as was done at one time for EFL, the Extended 
FORTRAN Language. Since the lex input specification is essentially language-independent, 
versions of this utility could be written to produce Ada, Modula-2, or Pascal code, and there are 
known historical implementations that do so. 

The current description of lex bypasses the issue of dealing with internationalized EREs in the lex 
source code or generated lexical analyzer. If it follows the model used by azvk (the source code is I 
assumed to be presented in the POSIX locale, but input and output are in the locale specified by I 
the environment variables), then the tables in the lexical analyzer produced by lex would 
interpret EREs specified in the lex source in terms of the environment variables specified when 
lex was executed. The desired effect would be to have the lexical analyzer interpret the EREs 
given in the lex source according to the environment specified when the lexical analyzer is 
executed, but this is not possible with the current lex technology. 

The description of octal and hexadecimal-digit escape sequences agrees with the ISO C standard 
use of escape sequences. See the RATIONALE for ed on page 369 for a discussion of bytes larger 
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than 9 bits being represented by octal values. Hexadecimal values can represent larger bytes and 
multi-byte characters directly, using as many digits as required. 

There is no detailed output format specification. The observed behavior of lex under four 
different historical implementations was that none of these implementations consistently 
reported the line numbers for error and warning messages. Furthermore, there was a desire that 
lex be allowed to output additional diagnostic messages. Leaving message formats unspecified 
avoids these formatting questions and problems with internationalization. 

Although the %x specifier for exclusive start conditions is not historical practice, it is believed to 
be a minor change to historical implementations and greatly enhances the usability of lex 
programs since it permits an application to obtain the expected functionality with fewer 
statements. 

The %array and %pointer declarations were added as a compromise between historical systems. 
The System V-based lex copies the matched text to a yytext array. The flex program, supported in 
BSD and GNU systems, uses a pointer. In the latter case, significant performance improvements 
are available for some scanners. Most historical programs should require no change in porting 
from one system to another because the string being referenced is null-terminated in both cases. 
(The method used by flex in its case is to null-terminate the token in place by remembering the 
character that used to come right after the token and replacing it before continuing on to the next 
scan.) Multi-file programs with external references to yytext outside the scanner source file 
should continue to operate on their historical systems, but would require one of the new 
declarations to be considered strictly portable. 

The description of EREs avoids unnecessary duplication of ERE details because their meanings 
within a lex ERE are the same as that for the ERE in this volume of IEEE Std. 1003.1-200x. 

The reason for the undefined condition associated with text beginning with a <blank> or within 
" % {" and " %}" delimiter lines appearing in the Rules section is historical practice. Both the BSD 
and System V lex copy the indented (or enclosed) input in the Rules section (except at the 
beginning) to unreachable areas of the yylex function (the code is written directly after a break 
statement). In some cases, the System V lex generates an error message or a syntax error, 
depending on the form of indented input. 

The intention in breaking the list of functions into those that may appear in lex.yy.c versus those 
that only appear in libl.a is that only those functions in libl.a can be reliably redefined by a 
portable application. 

The descriptions of standard output and standard error are somewhat complicated because 
historical lex implementations chose to issue diagnostic messages to standard output (unless -t 
was given). This standard allows this behavior, but leaves an opening for the more expected 
behavior of using standard error for diagnostics. Also, the System V behavior of writing the 
statistics when any table sizes are given is allowed, while BSD-derived systems can avoid it. The 
programmer can always precisely obtain the desired results by using either the -t or -n options. 

The OPERANDS section does not mention the use of - as a synonym for standard input; not all 
historical implementations support such usage for any of the file operands. 

A description of the translation table was deleted from early proposals because of its relatively 
low usage in historical applications. 

The change to the definition of the input function that allows buffering of input presents the 
opportunity for major performance gains in some applications. 

The following examples clarify the differences between lex regular expressions and regular 
expressions appearing elsewhere in this volume of IEEE Std. 1003.1-200x. For regular 
expressions of the form "r/x", the string matching r is always returned; confusion may arise 
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22005 when the beginning of x matches the trailing portion of r. For example, given the regular 

22006 expression "a*b/cc" and the input "aaabcc", yytext would contain the string "aaab" on this 

22007 match. But given the regular expression "x*/xy" and the input "xxxy", the token xxx, not xx, 

22008 is returned by some implementations because xxx matches " x * ". 

22009 In the rule "ab*/bc", the "b*" at the end of r extends r's match into the beginning of the 

22010 trailing context, so the result is unspecified. If this rule were "ab/bc", however, the rule 

22011 matches the text " ab " when it is followed by the text "be ". In this latter case, the matching of r 

22012 cannot extend into the beginning of x, so the result is specified. 

22013 FUTURE DIRECTIONS 

22014 None. 

22015 SEE ALSO 

22016 c89, yacc 

22017 CHANGE HISTORY 

22018 First released in Issue 2. 


22019 Issue 4 

22020 

22021 Issue 6 

22022 

22023 

22024 


Aligned with the ISO/IEC 9945-2:1993 standard. 

This utility is now marked as part of the C-Language Development Utilities option. 

The obsolescent -c option is withdrawn in this issue. 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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22025 NAME 

22026 link — call link () function 

22027 SYNOPSIS 

22028 xsi link filel file2 

22029 

22030 DESCRIPTION 

22031 The link utility shall perform the function call: 

22032 link (filel, file2); 

22033 A user may need appropriate privilege to invoke the link utility. 

22034 OPTIONS 

22035 None. 

22036 OPERANDS 

22037 The following operands shall be supported: 

22038 filel The path name of an existing file. 

22039 file2 The path name of the new directory entry to be created. 

22040 STDIN 

22041 Not used. 

22042 INPUT FILES 

22043 Not used. 


22044 ENVIRONMENT VARIABLES 

22045 The following environment variables shall affect the execution of link : 


22046 

22047 

22048 

22049 

22050 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contain an invalid setting, the utility behaves as if none of the variables had been 
set. 


22051 LC_ALL If set to a non-empty string value, override the values of all the other 

22052 internationalization variables. 


22053 

22054 

22055 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


22056 

22057 

22058 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


22059 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


22060 ASYNCHRONOUS EVENTS 

22061 Default. 


22062 STDOUT 

22063 None. 
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22064 STDERR 

22065 Used only for diagnostic messages. 

22066 OUTPUT FILES 

22067 None. 

22068 EXTENDED DESCRIPTION 

22069 None. 

22070 EXIT STATUS 

22071 The following exit values shall be returned: 

22072 0 Successful completion. 

22073 >0 An error occurred. 

22074 CONSEQUENCES OF ERRORS 

22075 Default. 

22076 APPLICATION USAGE 

22077 None. 

22078 EXAMPLES 

22079 None. 

22080 RATIONALE 

22081 None. 

22082 FUTURE DIRECTIONS 

22083 None. 

22084 SEE ALSO 

22085 In, unlink, the System Interfaces volume of IEEE Std. 1003.1-200x, link() 

22086 CHANGE HISTORY 

22087 First released in Issue 5. 
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22088 NAME 

22089 In — link files 

22090 SYNOPSIS 

22091 In [—fs] source_fHe target_file I 

22092 In [—fs] source_file . . . target_dir \ 

22093 DESCRIPTION I 

22094 In the first synopsis form, the In utility shall create a new directory entry (link), or if the -s I 

22095 option is specified a symbolic link, for the file specified by the source_file operand, at the I 

22096 destination path specified by the target_file operand. This first synopsis form shall be assumed 

22097 when the final operand does not name an existing directory; if more than two operands are 

22098 specified and the final is not an existing directory, an error shall result. 

22099 In the second synopsis form, the In utility shall create a new directory entry (link), or if the -s I 

22100 option is specified a symbolic link, for each file specified by a source_file operand, at a destination I 

22101 path in the existing directory named by target_dir. 

22102 If the last operand specifies an existing file of a type not specified by the System Interfaces 

22103 volume of IEEE Std. 1003.1-200x, the behavior is implementation-dependent. 

22104 The corresponding destination path for each source_file shall be the concatenation of the target I 

22105 directory path name, a slash character, and the last path name component of the source_file. The 

22106 second synopsis form shall be assumed when the final operand names an existing directory. 

22107 For each sourcejile: 

22108 1. If the destination path exists: 

22109 a. If the -f option is not specified. In shall write a diagnostic message to standard error, 

22110 do nothing more with the current sonrce_file, and go on to any remaining source_files. 

22111 b. Actions shall be performed equivalent to the unlink{ ) function defined in the System 

22112 Interfaces volume of IEEE Std. 1003.1-200x, called using destination as the path 

22113 argument. If this fails for any reason. In shall write a diagnostic message to standard 

22114 error, do nothing more with the current source_file r and go on to any remaining 

22115 source_files. 

22116 2. If the -s option is specified. In shall create a symbolic link named by the destination path I 

22117 and containing as its path name source_file. The In utility shall do nothing more with I 

22118 sonrce_file and shall go on to any remaining files. I 

22119 3. If sonrce_file is a symbolic link, actions shall be performed equivalent to the link () function I 

22120 using the object that source_file references as the pat lit argument and the destination path I 

22121 as the path2 argument. The In utility shall do nothing more with source_file and shall go on I 

22122 to any remaining files. I 

22123 4. Actions shall be performed equivalent to the link() function defined in the System I 

22124 Interfaces volume of IEEE Std. 1003.1-200x using source_file as the pathl argument, and the 

22125 destination path as the path2 argument. 

22126 OPTIONS 

22127 The In utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

22128 Section 12.2, Utility Syntax Guidelines. I 

22129 The following option shall be supported: 

22130 -f Force existing destination path names to be removed to allow the link. I 
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22131 -s Create symbolic links instead of hard links. 


22132 OPERANDS 

22133 The following operands shall be supported: 


22134 

22135 

22136 


sourceJile A path name of a file to be linked. If the -s option is specified, no restrictions on I 

the type of file or on its existence shall be made. If the -s option is not specified, I 
whether a directory can be linked is implementation-dependent. I 


22137 


target Jile The path name of the new directory entry to be created. 


22138 

22139 


target_dir A path name of an existing directory in which the new directory entries are I 
created. I 


22140 STDIN 

22141 Not used. 


22142 INPUT FILES 

22143 None. 


22144 ENVIRONMENT VARIABLES 

22145 The following environment variables shall affect the execution of In: 


22146 

22147 

22148 

22149 

22150 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


22151 

22152 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


22153 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

22154 characters (for example, single-byte as opposed to multi-byte characters in 

22155 arguments). 

22156 LC_MESSAGES 

22157 Determine the locale that should be used to affect the format and contents of 

22158 diagnostic messages written to standard error. 

22159 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

22160 ASYNCHRONOUS EVENTS 

22161 Default. 


22162 STDOUT 

22163 Not used. 


22164 STDERR 

22165 Used only for diagnostic messages. 

22166 OUTPUT FILES 

22167 None. 


22168 EXTENDED DESCRIPTION 

22169 None. 


22170 EXIT STATUS 

22171 The following exit values shall be returned: 

22172 0 All the specified files were linked successfully. 
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22173 >0 An error occurred. 

22174 CONSEQUENCES OF ERRORS 

22175 Default. 

22176 APPLICATION USAGE 

22177 None. 

22178 EXAMPLES 

22179 None. 

22180 RATIONALE 

22181 Some historic versions of In (including the one specified by the SVID, unlink the destination file, 

22182 if it exists, by default. If the mode does not permit writing, these versions prompt for 

22183 confirmation before attempting the unlink. In these versions the -f option causes In not to 

22184 attempt to prompt for confirmation. 

22185 This allows In to succeed in creating links when the target file already exists, even if the file itself 

22186 is not writable (although the directory must be). Early proposals specified this functionality. 

22187 This volume of IEEE Std. 1003.1-200x does not allow the In utility to unlink existing destination 

22188 paths by default for the following reasons: 

22189 • The In utility has historically been used to provide locking for shell applications, a usage that 

22190 is incompatible with In unlinking the destination path by default. There was no 

22191 corresponding technical advantage to adding this functionality. 

22192 • This functionality gave In the ability to destroy the link structure of files, which changes the 

22193 historical behavior of In. 

22194 • This functionality is easily replicated with a combination of rm and In. 

22195 • It is not historical practice in many systems; BSD and BSD-derived systems do not support 

22196 this behavior. Unfortunately, whichever behavior is selected can cause scripts written 

22197 expecting the other behavior to fail. 

22198 • It is preferable that In perform in the same manner as the link() function, which does not 

22199 permit the target to exist already. 

22200 This volume of IEEE Std. 1003.1-200x retains the -f option to provide support for shell scripts 

22201 depending on the SVID semantics. It seems likely that shell scripts would not be written to 

22202 handle prompting by In and would therefore have specified the -f option. 

22203 The -f option is an undocumented feature of many historical versions of the In utility, allowing 

22204 linking to directories. These versions require modification. 

22205 Early proposals of this volume of IEEE Std. 1003.1-200x also required an -i option, which 

22206 behaved like the -i options in cp and mv, prompting for confirmation before unlinking existing 

22207 files. This was not historical practice for the In utility and has been omitted. 

22208 FUTURE DIRECTIONS 

22209 None. 

22210 SEE ALSO 

22211 chmod,find, pax, rm, the System Interfaces volume of IEEE Std. 1003.1-200x, link () 

22212 CHANGE HISTORY 

22213 First released in Issue 2. 


584 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


In 


22214 Issue 4 

22215 Aligned with the ISO/IEC 9945-2:1993 standard. I 

22216 Issue 6 I 

22217 The In utility is updated to include symbolic link processing as defined in the IEEE P1003.2b I 

22218 draft standard. I 
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22219 NAME 

22220 locale — get locale-specific information 

22221 SYNOPSIS 

22222 locale [-a | -m] 


22223 locale [—ck] name. . . 


22224 DESCRIPTION 

22225 The locale utility shall write information about the current locale environment, or all public 

22226 locales, to the standard output. For the purposes of this section, a public locale is one provided by 

22227 the implementation that is accessible to the application. 

22228 When locale is invoked without any arguments, it shall summarize the current locale 

22229 environment for each locale category as determined by the settings of the environment variables I 

22230 defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

22231 When invoked with operands, it shall write values that have been assigned to the keywords in 

22232 the locale categories, as follows: 

22233 • Specifying a keyword name shall select the named keyword and the category containing that 

22234 keyword. 

22235 • Specifying a category name shall select the named category and all keywords in that 

22236 category. 


22237 OPTIONS 

22238 The locale utility shall conform to the System Interface Definitions volume of I 

22239 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

22240 The following options shall be supported: 


22241 -a 

22242 

22243 

22244 


Write information about all available public locales. The available locales shall 
include POSIX, representing the POSIX locale. The manner in which the 
implementation determines what other locales are available is implementation- 
dependent. 


22245 -C 

22246 

22247 

22248 


Write the names of selected locale categories; see the STDOUT section. The -c 
option increases readability when more than one category is selected (for example, 
via more than one keyword name or via a category name). It is valid both with 
and without the -k option. 


22249 -k Write the names and values of selected keywords. The implementation may omit 

22250 values for some keywords; see the OPERANDS section. 


22251 -m Write names of available charmaps; see the System Interface Definitions volume of I 

22252 IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set. I 


22253 OPERANDS 

22254 The following operand shall be supported: 


22255 

22256 

22257 

22258 

22259 

22260 
22261 
22262 


name The name of a locale category as defined in the System Interface Definitions I 

volume of IEEE Std. 1003.1-200x, Chapter 7, Locale, the name of a keyword in a I 
locale category, or the reserved name charmap. The named category or keyword 
shall be selected for output. If a single name represents both a locale category name 
and a keyword name in the current locale, the results are unspecified. Otherwise, 
both category and keyword names can be specified as name operands, in any 
sequence. It is implementation-dependent whether any keyword values are 
written for the categories LC_CTYPE and LC_COLLATE. 
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22263 STDIN 

22264 Not used. 

22265 INPUT FILES 

22266 None. 


22267 ENVIRONMENT VARIABLES 

22268 The following environment variables shall affect the execution of locale: 


22269 

22270 

22271 

22272 

22273 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


22274 

22275 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


22276 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

22277 characters (for example, single-byte as opposed to multi-byte characters in 

22278 arguments and input files). 

22279 LC_MESSAGES 

22280 Determine the locale that should be used to affect the format and contents of 

22281 diagnostic messages written to standard error. 

22282 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

22283 xsi The application shall ensure that the LANG, LC_*, and NLSPATH environment variables specify I 

22284 the current locale environment to be written out; they shall be used if the -a option is not I 

22285 specified. 


22286 ASYNCHRONOUS EVENTS 

22287 Default. 


22288 STDOUT 

22289 If locale is invoked without any options or operands, the names and values of the LANG and 

22290 LC_* environment variables described in this volume of IEEE Std. 1003.1-200x shall be written to 

22291 the standard output, one variable per line, with LANG first, and each line using the following 

22292 format. Only those variables set in the environment and not overridden by LC_ALL shall be 

22293 written using this format: 

22294 "%s=%s\n", <variable_name>, <value> 

22295 The names of those LC_* variables associated with locale categories defined in this volume of 

22296 IEEE Std. 1003.1-200x that are not set in the environment or are overridden by LC_ALL shall be 

22297 written in the following format: 

22298 "%s = \" "%s\" "\n", <variable_name>, <implied value> 

22299 The <implied value> shall be the name of the locale that has been selected for that category by the 

22300 implementation, based on the values in LANG and LC_ALL, as described in the System Interface I 

22301 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

22302 The <value> and <implied value> shown above shall be properly quoted for possible later reentry 

22303 to the shell. The <value> shall not be quoted using double-quotes (so that it can be distinguished 

22304 by the user from the <implied value> case, which always requires double-quotes). 

22305 The LC_ALL variable shall be written last, using the first format shown above. If it is not set, it 

22306 shall be written as: 


Commands and Utilities, Issue 6 


587 



locale 


Utilities 


22307 

" LC_ 

_ALL=\n" 

22308 

If any arguments are specified: 

22309 

22310 

1 . 

If the -a option is specified, the names of all the public locales shall be written, each in the 
following format: 

22311 


"%s\n", <locale name> 

22312 

22313 

2 . 

If the -c option is specified, the names of all selected categories shall be written, each in the 
following format: 

22314 


"%s\n", <category name> 

22315 

22316 


If keywords are also selected for writing (see following items), the category name output 
shall precede the keyword output for that category. 

22317 

22318 


If the -c option is not specified, the names of the categories shall not be written; only the 
keywords, as selected by the <name> operand, shall be written. 

22319 

22320 

3. 

If the -k option is specified, the names and values of selected keywords shall be written. If 
a value is non-numeric, it shall be written in the following format: 

22321 


"%s=\"%s\"\n", <keyword name>, <keyword value> 

22322 

22323 

22324 


If the keyword was charmap, the name of the charmap (if any) that was specified via the 
localedef -f option when the locale was created shall be written, with the word charmap as 
<keyzvord name>. 

22325 


If a value is numeric, it shall be written in one of the following formats: 

22326 


"%s=%d\n", <keyword name>, <keyword value> 

22327 


"%s=%c%o\n", <keyword name>, <escape character>, <keyword value> 

22328 


"%s=%cx%x\n" , <keyword name>, <escape character>, <keyword value> 

22329 

22330 

22331 


where the <escape character> is that identified by the escape_char keyword in the current 
locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 7.3, 
Locale Definition. 

22332 

22333 

22334 


Compound keyword values (list entries) shall be separated in the output by semicolons. 
When included in keyword values, the semicolon, the double-quote, the backslash, and 
any control character shall be preceded (escaped) with the escape character. 

22335 

22336 

4. 

If the -k option is not specified, selected keyword values shall be written, each in the 
following format: 

22337 


"%s\n", <keyword value> 

22338 

22339 


If the keyword was charmap, the name of the charmap (if any) that was specified via the 
localedef- f option when the locale was created shall be written. 

22340 

22341 

5. 

If the -m option is specified, then a list of all available charmaps shall be written, each in 
the format: 

22342 


"%s\n", <charmap> 

22343 

22344 


where <charmap> is in a format suitable for use as the option-argument to the localedef -f 
option. 
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22345 STDERR 

22346 Used only for diagnostic messages. 

22347 OUTPUT FILES 

22348 None. 

22349 EXTENDED DESCRIPTION 

22350 None. 

22351 EXIT STATUS 

22352 The following exit values shall be returned: 

22353 0 All the requested information was found and output successfully. 

22354 >0 An error occurred. 

22355 CONSEQUENCES OF ERRORS 

22356 Default. 

22357 APPLICATION USAGE 

22358 If the LANG environment variable is not set or set to an empty value, or one of the LC_* 

22359 environment variables is set to an unrecognized value, the actual locales assumed (if any) are 

22360 implementation-dependent as described in the System Interface Definitions volume of I 

22361 IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

22362 Implementations are not required to write out the actual values for keywords in the categories 

22363 LC_CTYPE and LC_COLLATE ; however, they must write out the categories (allowing an 

22364 application to determine, for example, which character classes are available). 

22365 EXAMPLES 

22366 In the following examples, the assumption is that locale environment variables are set as 

22367 follows: 

22368 LANG=locale_x 

22369 LC_COLLATE=locale_y 

22370 The command locale would result in the following output: 

22371 LANG=locale_x 

22372 LC_CTYPE= " locale_x " 

22373 LC_COLLATE=locale_y 

22374 LC_TIME=" locale_x " 

22375 LC_NUMERIC= " locale_x " 

22376 L C_MONE T AR Y = " 1 o c a 1 e_x " 

22377 LC_MESSAGES=" locale_x " 

22378 LC_ALL= 

22379 The order of presentation of the categories is not specified by this volume of 

22380 IEEE Std. 1003.1-200x. 

22381 The command: 

22382 LC_ALL=POSIX locale — ck decimal_point 

22383 would produce: 

22384 LC_NUMERIC 

22385 decimal_point = " . " 

22386 The following command shows an application of locale to determine whether a user-supplied 

22387 response is affirmative: 
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22388 if printf "%s\n" "$response" I grep — Eq "$ (locale yesexpr) " 

22389 then 

22390 affirmative processing goes here 

22391 else 

22392 non-affirmative processing goes here 

22393 fi 

22394 RATIONALE 

22395 The output for categories LC_CTYPE and LC_COLLATE has been made implementation- 

22396 dependent because there is a questionable value in having a shell script receive an entire array of 

22397 characters. It is also difficult to return a logical collation description, short of returning a 

22398 complete localedef source. 

22399 The -m option was included to allow applications to query for the existence of charmaps. The 

22400 output is a list of the charmaps (implementation-supplied and user-supplied, if any) on the 

22401 system. 

22402 The -c option was included for readability when more than one category is selected (for 

22403 example, via more than one keyword name or via a category name). It is valid both with and 

22404 without the -k option. 

22405 The charmap keyword, which returns the name of the charmap (if any) that was used when the 

22406 current locale was created, was included to allow applications needing the information to 

22407 retrieve it. 

22408 FUTURE DIRECTIONS 

22409 None. I 

22410 SEE ALSO 

22411 localedef, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 7.3, Locale I 

22412 Definition I 

22413 CHANGE HISTORY 

22414 First released in Issue 4. 

22415 Issue 5 

22416 FUTURE DIRECTIONS section added. I 

22417 Issue 6 I 

22418 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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22419 

22420 

22421 

22422 

22423 

22424 

22425 

22426 

22427 

22428 

22429 

22430 

22431 

22432 

22433 

22434 

22435 

22436 

22437 

22438 

22439 

22440 

22441 

22442 

22443 

22444 

22445 

22446 

22447 

22448 

22449 

22450 

22451 

22452 

22453 

22454 

22455 

22456 

22457 

22458 

22459 

22460 

22461 

22462 


NAME 

localedef — define locale environment 

SYNOPSIS 

localedef [—c][—f charmap ][—i sourcefile ][—u code_set_name] name I 

DESCRIPTION | 

The localedef utility shall convert source definitions for locale categories into a format usable by 
the functions and utilities whose operational behavior is determined by the setting of the locale 
environment variables defined in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 7, Locale. It is implementation-dependent whether users have the I 
capability to create new locales, in addition to those supplied by the implementation. If the 
symbolic constant POSIX2_LOCALEDEF is defined, the system supports the creation of new 
xsi locales. On XSI-conformant systems, the symbolic constant POSIX2_LOCALEDEF shall be 
defined. 

The utility shall read source definitions for one or more locale categories belonging to the same 
locale from the file named in the -i option (if specified) or from standard input. 

The name operand identifies the target locale. The utility shall support the creation of public, or 
generally accessible locales, as well as private, or restricted-access locales. Implementations may 
restrict the capability to create or modify public locales to users with the appropriate privileges. 

Each category source definition shall be identified by the corresponding environment variable 
name and terminated by an END category-name statement. The following categories shall be 
supported. In addition, the input may contain source for implementation-dependent categories. 

LC_CTYPE Defines character classification and case conversion. 

LC_COLLATE 

Defines collation rules. 

LC_MONETARY 

Defines the format and symbols used in formatting of monetary information. 
LC_NUMERIC 

Defines the decimal delimiter, grouping, and grouping symbol for non-monetary 
numeric editing. 

LC_TIME Defines the format and content of date and time information. 

LC_MESSAGES 

Defines the format and values of affirmative and negative responses. 

OPTIONS 

The localedef utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-c Create permanent output even if warning messages have been issued. 

-f charmap Specify the path name of a file containing a mapping of character symbols and 
collating element symbols to actual character encodings. The format of the 
charmap is described under the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 6.4, Character Set Description File. The application I 
shall ensure that this option is specified if symbolic names (other than collating I 
symbols defined in a collating-symbol keyword) are used. If the -f option is not I 
present, an implementation-dependent character mapping shall be used. 
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22463 

22464 

22465 

22466 

22467 

22468 

22469 

22470 

22471 

22472 

22473 

22474 

22475 

22476 

22477 

22478 

22479 

22480 

22481 

22482 

22483 

22484 

22485 

22486 

22487 

22488 

22489 

22490 

22491 

22492 

22493 

22494 

22495 

22496 

22497 

22498 

22499 

22500 

22501 

22502 

22503 

22504 

22505 

22506 

22507 

22508 


-i inputfile The path name of a file containing the source definitions. If this option is not 
present, source definitions shall be read from standard input. The format of the 
inputfile is described in the System Interface Definitions volume of I 

IEEE Std. 1003.1-200x, Section 7.3, Locale Definition. I 

-u code_set_name Specify the name of a codeset used as the target mapping of character symbols I 
and collating element symbols whose encoding values are defined in terms of the I 
ISO/IEC 10646-1:1993 standard position constant values. I 

OPERANDS 

The following operand shall be supported: 

name Identifies the locale; see the System Interface Definitions volume of I 

IEEE Std. 1003.1-200x, Chapter 7, Locale for a description of the use of this name. If I 

the name contains one or more slash characters, name shall be interpreted as a path 
name where the created locale definitions shall be stored. If name does not contain 
any slash characters, the interpretation of the name is implementation-dependent 
and the locale shall be public. This capability may be restricted to users with 
appropriate privileges. (As a consequence of specifying one name, although several 
categories can be processed in one execution, only categories belonging to the 
same locale can be processed.) 

STDIN 

Unless the -i option is specified, the standard input shall be a text file containing one or more I 
locale category source definitions, as described in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 7.3, Locale Definition. When lines are continued using the escape I 
character mechanism, there is no limit to the length of the accumulated continued line. I 

INPUT FILES 

The character set mapping file specified as the charmap option-argument is described under the I 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.4, Character Set I 
Description File. If a locale category source definition contains a copy statement, as defined in I 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale, and the I 
copy statement names a valid, existing locale, then localedef shall behave as if the source 
definition had contained a valid category source definition for the named locale. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of localedef: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

(This variable has no affect on localedef; the POSIX locale is used for this category.) 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). This variable has no affect on the processing of localedef 
input data; the POSIX locale is used for this purpose, regardless of the value of this 
variable. 
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22509 LC_MESSAGES 

22510 Determine the locale that should be used to affect the format and contents of 

22511 diagnostic messages written to standard error. 

22512 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

22513 ASYNCHRONOUS EVENTS 

22514 Default. 

22515 STDOUT 

22516 The utility shall report all categories successfully processed, in an unspecified format. 

22517 STDERR 

22518 Used only for diagnostic messages. 

22519 OUTPUT FILES 

22520 The format of the created output is unspecified. If the name operand does not contain a slash, the 

22521 existence of an output file for the locale is unspecified. 

22522 EXTENDED DESCRIPTION 

22523 When the -u option is used, the code_set_name option-argument shall be interpreted as an 

22524 implementation-dependent name of a codeset to which the ISO/IEC 10646-1:1993 standard 

22525 position constant values shall be converted via an implementation-dependent method. Both the 

22526 ISO/IEC 10646-1:1993 standard position constant values and other formats (decimal, 

22527 hexadecimal, or octal) shall be valid as encoding values within the clmrmap file. The codeset 

22528 represented by the implementation-dependent name can be any codeset that is supported by the 

22529 implementation. 

22530 When conflicts occur between the charmap specification of <code_set_name>, <mb_cur_max>, or 

22531 <mb_cnr_min> and the implementation-dependent interpretation of these respective items for 

22532 the codeset represented by the -u option-argument code_set_name , the result is unspecified. 

22533 When conflicts occur between the charmap encoding values specified for symbolic names of 

22534 characters of the portable character set and the implementation-dependent assignment of 

22535 character encoding values, the result is unspecified. 

22536 If a non-printable character in the charmap has a width specified that is not -1, localedef shall 

22537 generate a warning. 

22538 EXIT STATUS 

22539 The following exit values shall be returned: 

22540 0 No errors occurred and the locales were successfully created. 

22541 1 Warnings occurred and the locales were successfully created. 

22542 2 The locale specification exceeded implementation limits or the coded character set or sets 

22543 used were not supported by the implementation, and no locale was created. 

22544 3 The capability to create new locales is not supported by the implementation. 

22545 >3 Warnings or errors occurred and no output was created. 

22546 CONSEQUENCES OF ERRORS 

22547 If an error is detected, no permanent output shall be created. 

22548 If warnings occur, permanent output shall be created if the -c option was specified. The 

22549 following conditions shall cause warning messages to be issued: 

22550 • If a symbolic name not found in the charmap file is used for the descriptions of the LC_CTYPE 

22551 or LC_COLLATE categories (for other categories, this shall be an error condition). 
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22552 • If the number of operands to the order keyword exceeds the {COLL_WEIGHTS_MAX} limit. 

22553 • If optional keywords not supported by the implementation are present in the source. I 

22554 • If a non-printable character has a width specified other than-1. I 

22555 Other implementation-dependent conditions may also cause warnings. 

22556 APPLICATION USAGE 

22557 The charmap definition is optional, and is contained outside the locale definition. This allows 

22558 both completely self-defined source files, and generic sources (applicable to more than one 

22559 codeset). To aid portability, all charmap definitions must use the same symbolic names for the 

22560 portable character set. As explained in the System Interface Definitions volume of I 

22561 IEEE Std. 1003.1-200x, Section 6.4, Character Set Description File, it is implementation- I 

22562 dependent whether or not users or applications can provide additional character set description I 

22563 files. Therefore, the -f option might be operable only when an implementation-dependent 

22564 charmap is named. 

22565 EXAMPLES 

22566 None. 

22567 RATIONALE 

22568 The output produced by the localedef utility is implementation-dependent. The name operand is 

22569 used to identify the specific locale. (As a consequence, although several categories can be 

22570 processed in one execution, only categories belonging to the same locale can be processed.) 

22571 FUTURE DIRECTIONS 

22572 None. 

22573 SEE ALSO 

22574 locale, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 7.3, Locale I 

22575 Definition I 

22576 CHANGE HISTORY 

22577 First released in Issue 4. I 

22578 Issue 6 I 

22579 The -u option is added, as specified in the IEEE P1003.2b draft standard. I 

22580 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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22581 NAME 

22582 logger — log messages 

22583 SYNOPSIS 

22584 logger string . . . 

22585 DESCRIPTION 

22586 The logger utility saves a message, in an unspecified manner and format, containing the string 

22587 operands provided by the user. The messages are expected to be evaluated later by personnel 

22588 performing system administration tasks. 

22589 It is implementation-dependent whether messages written in locales other than the POSIX locale 

22590 are effective. 

22591 OPTIONS 

22592 None. 

22593 OPERANDS 

22594 The following operand shall be supported: 

22595 string One of the string arguments whose contents are concatenated together, in the 

22596 order specified, separated by single <space> characters. 

22597 STDIN 

22598 Not used. 

22599 INPUT FILES 

22600 None. 

22601 ENVIRONMENT VARIABLES 


22602 

The following environment variables shall affect the execution of logger: 

22603 

22604 

22605 

22606 

22607 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

22608 

22609 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

22610 

22611 

22612 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

22613 

22614 

22615 

22616 

22617 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. (This means diagnostics from logger 
to the user or application, not diagnostic messages that the user is sending to the 
system administrator.) 

22618 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


22619 ASYNCHRONOUS EVENTS 

22620 Default. 

22621 STDOUT 

22622 Not used. 
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22623 STDERR 

22624 Used only for diagnostic messages. 

22625 OUTPUT FILES 

22626 Unspecified. 

22627 EXTENDED DESCRIPTION 

22628 None. 

22629 EXIT STATUS 

22630 The following exit values shall be returned: 

22631 0 Successful completion. 

22632 >0 An error occurred. 

22633 CONSEQUENCES OF ERRORS 

22634 Default. 

22635 APPLICATION USAGE 

22636 This utility allows logging of information for later use by a system administrator or programmer 

22637 in determining why non-interactive utilities have failed. The locations of the saved messages, 

22638 their format, and retention period are all unspecified. There is no method for a portable 

22639 application to read messages, once written. 

22640 EXAMPLES 

22641 A batch application, running non-interactively, tries to read a configuration file and fails; it may 

22642 attempt to notify the system administrator with: 

22643 logger myname: unable to read file foo. [timestamp] 

22644 RATIONALE 

22645 The standard developers believed strongly that some method of alerting administrators to errors 

22646 was necessary. The obvious example is a batch utility, running non-interactively, that is unable 

22647 to read its configuration files or that is unable to create or write its results file. However, the 

22648 standard developers did not wish to define the format or delivery mechanisms as they have 

22649 historically been (and will probably continue to be) very system-specific, as well as involving 

22650 functionality clearly outside of the scope of this volume of IEEE Std. 1003.1-200x. 

22651 The text with LC_MESSAGES about diagnostic messages means diagnostics from logger to the 

22652 user or application, not diagnostic messages that the user is sending to the system administrator. 

22653 Multiple string arguments are allowed, similar to echo, for ease-of-use. 

22654 Like the utilities mailx and Ip, logger is admittedly difficult to test. This was not deemed sufficient 

22655 justification to exclude these utilities from this volume of IEEE Std. 1003.1-200x. It is also 

22656 arguable that they are, in fact, testable, but that the tests themselves are not portable. 

22657 FUTURE DIRECTIONS 

22658 None. 

22659 SEE ALSO 

22660 mailx, write 

22661 CHANGE HISTORY 

22662 First released in Issue 4. 
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22663 NAME 

22664 logname — return the user's login name 

22665 SYNOPSIS 

22666 logname 

22667 DESCRIPTION 

22668 The logname utility shall write the user's login name to standard output. The login name shall be 

22669 the string that would be returned by the getlogin () function defined in the System Interfaces 

22670 volume of IEEE Std. 1003.1-200x. Under the conditions where the getlogin () function would fail, 

22671 the logname utility shall write a diagnostic message to standard error and exit with a non-zero 

22672 exit status. 

22673 OPTIONS 

22674 None. 

22675 OPERANDS 

22676 None. 

22677 STDIN 

22678 Not used. 

22679 INPUT FILES 

22680 None. 


22681 ENVIRONMENT VARIABLES 

22682 The following environment variables shall affect the execution of logname: 


22683 

22684 

22685 

22686 
22687 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


22688 LC_ALL If set to a non-empty string value, override the values of all the other 

22689 internationalization variables. 


22690 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

22691 characters (for example, single-byte as opposed to multi-byte characters in 

22692 arguments). 

22693 LC_MESSAGES 

22694 Determine the locale that should be used to affect the format and contents of 

22695 diagnostic messages written to standard error. 

22696 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

22697 ASYNCHRONOUS EVENTS 

22698 Default. 


22699 STDOUT 

22700 The logname utility output shall be a single line consisting of the user's login name: 

22701 "%s\n" , <login name> 

22702 STDERR 

22703 Used only for diagnostic messages. 


Commands and Utilities, Issue 6 


597 



logname 


Utilities 


22704 OUTPUT FILES 

22705 None. 

22706 EXTENDED DESCRIPTION 

22707 None. 

22708 EXIT STATUS 

22709 The following exit values shall be returned: 

22710 0 Successful completion. 

22711 >0 An error occurred. 

22712 CONSEQUENCES OF ERRORS 

22713 Default. 

22714 APPLICATION USAGE 

22715 The logname utility explicitly ignores the LOGNAME environment variable because environment 

22716 changes could produce erroneous results. 

22717 EXAMPLES 

22718 None. 

22719 RATIONALE 

22720 The passwd file is not listed as required because the implementation may have other means of 

22721 mapping login names. 

22722 FUTURE DIRECTIONS 

22723 None. 

22724 SEE ALSO 

22725 id, who 

22726 CHANGE HISTORY 

22727 First released in Issue 2. 

22728 Issue 4 

22729 Aligned with the ISO/IEC 9945-2:1993 standard. 
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22730 NAME 

22731 lp — send files to a printer 

22732 SYNOPSIS 

22733 man lp [—c] [—d dest] [—n copies ] [-msw] [—o option ] . . . [—t title ] [file. . .] 

22734 DESCRIPTION 

22735 The lp utility shall copy the input files to an output destination in an unspecified manner. The 

22736 default output destination should be to a hardcopy device, such as a printer or microfilm 

22737 recorder, that produces non-volatile, human-readable documents. If such a device is not 

22738 available to the application, or if the system provides no such device, the Ip utility shall exit with 

22739 a non-zero exit status. 


22740 The actual writing to the output device may occur some time after the Ip utility successfully 

22741 exits. During the portion of the writing that corresponds to each input file, the implementation 

22742 shall guarantee exclusive access to the device. 


22743 man The lp utility shall associate a unique request ID with each request. 


22744 Normally, a banner page is produced to separate and identify each print job. This page may be 

22745 suppressed by implementation-dependent conditions, such as an operator command or one of 

22746 the -o option values. 


22747 OPTIONS 

22748 The lp utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

22749 Section 12.2, Utility Syntax Guidelines. I 

22750 The following options shall be supported: 


22751 -C 

22752 

22753 

22754 

22755 

22756 

22757 

22758 


Exit only after further access to any of the input files is no longer required. The 
application can then safely delete or modify the files without affecting the output 
operation. Normally, files are not copied, but are linked whenever possible. If the 
-c option is not given, then the user should be careful not to remove any of the 
files before the request has been printed in its entirety. It should also be noted that 
in the absence of the -c option, any changes made to the named files after the 
request is made but before it is printed are reflected in the printed output. On some 
systems, -c may be on by default. 


22759 MAN 

22760 

22761 

22762 

22763 

22764 


-d dest Specify a string that names the destination (dest). If dest is a printer, the request 

shall be printed only on that specific printer. If dest is a class of printers, the request 
shall be printed on the first available printer that is a member of the class. Under 
certain conditions (printer unavailability, file space limitation, and so on), requests 
for specific destinations need not be accepted. Destination names vary between 
systems. 


22765 

22766 

22767 

22768 


If -d is not specified, and neither the LPDEST nor PRINTER environment variable 
is set, an unspecified destination is used. The -d dest option shall take precedence 
over LPDEST, which in turn shall take precedence over PRINTER. Results are 
undefined when dest contains a value that is not a valid destination name. 


22769 man un -m Send mail (see mailx on page 619) after the files have been printed. By default, no 

22770 mail is sent upon normal completion of the print request. 

22771 -n copies Write copies number of copies of the files, where copies is a positive decimal integer. 

22772 The methods for producing multiple copies and for arranging the multiple copies 

22773 when multiple file operands are used are unspecified, except that each file shall be 

22774 output as an integral whole, not interleaved with portions of other files. 
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22777 

22778 

22779 

22780 

22781 
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22783 

22784 

22785 
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22791 

22792 
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22797 
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22799 

22800 
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22807 

22808 
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22813 

22814 
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man un -o option Specify printer-dependent or class-dependent options. Several such option s may be 
collected by specifying the -o option more than once. 

man pi -s Suppress messages from Ip such as "request id is .. 


man un -t title Write title on the banner page of the output. 


MAN UN 

-w 

Write a message on the useds terminal after the files have been printed. If the user 
is not logged in, then mail shall be sent instead. 

OPERANDS 

The following operand shall be supported: 


file 

A path name of a file to be output. If no file operands are specified, or if a file 
operand is ' , the standard input shall be used. If a file operand is used, but the 

-c option is not specified, the process performing the writing to the output device 
may have user and group permissions that differ from that of the process invoking 
lv. 

STDIN 

The standard input is used only if no file operands are specified, or if a file operand is ' - '. See 
the INPUT FILES section. 

INPUT FILES 

The input files shall be text files. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of Ip: 


LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 


LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

MAN 

LCJTIME 

Determine the format and contents of date and time strings displayed in the Ip 
banner page, if any. 


LPDEST 

Determine the destination. If the LPDEST environment variable is not set, the 
PRINTER environment variable shall be used. The -d dest option takes precedence 
over LPDEST. Results are undefined when -d is not specified and LPDEST 
contains a value that is not a valid destination name. 

XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


PRINTER 

Determine the output device or destination. If the LPDEST and PRINTER 
environment variables are not set, an unspecified output device is used. The -d 
dest option and the LPDEST environment variable shall take precedence over 
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22819 PRINTER. Results are undefined when -d is not specified, LPDEST is unset, and 

22820 PRINTER contains a value that is not a valid device or destination name. 

22821 ASYNCHRONOUS EVENTS 

22822 Default. 

22823 STDOUT 

22824 man The Ip utility shall write a request ID to the standard output, unless -s is specified. The format of 

22825 the message is unspecified. The request ID can be used on systems supporting the historical 

22826 cancel and Ipstat utilities. 

22827 STDERR 

22828 Used only for diagnostic messages. 

22829 OUTPUT FILES 

22830 None. 

22831 EXTENDED DESCRIPTION 

22832 None. 

22833 EXIT STATUS 

22834 The following exit values shall be returned: 

22835 0 All input files were processed successfully. 

22836 >0 No output device was available, or an error occurred. 

22837 CONSEQUENCES OF ERRORS 

22838 Default. 

22839 APPLICATION USAGE 

22840 The pr and fold utilities can be used to achieve reasonable formatting for the implementation's 

22841 default page size. 

22842 A portable application can use one of the file operands only with the -c option or if the file is 

22843 publicly readable and guaranteed to be available at the time of printing. This is because the 

22844 standard gives the implementation the freedom to queue up the request for printing at some 

22845 later time by a different process that might not be able to access the file. 

22846 EXAMPLES 

22847 1. To print file file: 

22848 lp -c file 

22849 2. To print multiple files with headers: 

22850 pr filel file2 | lp 

22851 RATIONALE 

22852 The Ip utility was designed to be a basic version of a utility that is already available in many 

22853 historical implementations. The standard developers considered that it should be implementable 

22854 simply as: 

22855 cat "$@" > /dev/lp 

22856 after appropriate processing of options, if that is how the implementation chose to do it and if 

22857 exclusive access could be granted (so that two users did not write to the device simultaneously). 

22858 Although in the future the standard developers may add other options to this utility, it should 

22859 always be able to execute with no options or operands and send the standard input to an 

22860 unspecified output device. 
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22861 

22862 

22863 

22864 

22865 

22866 
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lp Utilities 


This volume of IEEE Std. 1003.1-200x makes no representations concerning the format of the 
printed output, except that it must be "human-readable" and "non-volatile". Thus, writing by 
default to a disk or tape drive or a display terminal would not qualify. (Such destinations are not 
prohibited when -d dest, LPDEST, or PRINTER are used, however.) 

This volume of IEEE Std. 1003.1-200x is worded such that a "print job" consisting of multiple 
input files, possibly in multiple copies, is guaranteed to print so that any one file is not 
intermixed with another, but there is no statement that all the files or copies have to print out 
together. 

The -c option may imply a spooling operation, but this is not required. The utility can be 
implemented to wait until the printer is ready and then wait until it is finished. Because of that, 
there is no attempt to define a queuing mechanism (priorities, classes of output, and so on). 

On some historical systems, the request ID reported on the STDOUT can be used to later cancel 
or find the status of a request using utilities not defined in this volume of IEEE Std. 1003.1-200x. 

Although the historical System V lp and BSD Ipr utilities have provided similar functionality, 
they used different names for the environment variable specifying the destination printer. Since 
the name of the utility here is lp, LPDEST (used by the System V Ip utility) was given precedence 
over PRINTER (used by the BSD Ipr utility). Since environments of users frequently contain one 
or the other environment variable, the lp utility is required to recognize both. If this was not 
done, many applications would send output to unexpected output devices when users moved 
from system to system. 

Some have commented that Ip has far too little functionality to make it worthwhile. Requests 
have proposed additional options or operands or both that added functionality. The requests 
included: 

• Wording requiring the output to be "hardcopy" 

• A requirement for multiple printers 

• Options for supporting various page-description languages 

Given that a compliant system is not required to even have a printer, placing further restrictions 
upon the behavior of the printer is not useful. Since hardcopy format is so application- 
dependent, it is difficult, if not impossible, to select a reasonable subset of functionality that 
should be required on all compliant systems. 

The term "unspecified" is used in this section in lieu of "implementation-dependent" as most 
known implementations would not be able to make definitive statements in their conformance 
documents: the existence and usage of printers is very dependent on how the system 
administrator configures each individual system. 

Since the default destination, device type, queuing mechanisms, and acceptable forms of input 
are all unspecified, usage guidelines for what a portable application can do are as follows: 

• Use the command in a pipeline, or with -c, so that there are no permission problems and the 
files can be safely deleted or modified. 

• Limit output to text files of reasonable line lengths and printable characters and include no 
device-specific formatting information, such as a page description language. The meaning of 
"reasonable" in this context can only be answered as a quality-of-implementation issue, but 
it should be apparent from historical usage patterns in the industry and the locale. The pr and 
fold utilities can be used to achieve reasonable formatting for the default page size of the 
implementation. 
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Alternatively, the application can arrange its installation in such a way that it requires the 
system administrator or operator to provide the appropriate information on Ip options and 
environment variable values. 

At a minimum, having this utility in this volume of IEEE Std. 1003.1-200x tells the industry that 
portable applications require a means to print output and provides at least a command name 
and LPDEST routing mechanism that can be used for discussions between vendors, application 
writers, and users. The use of “should" in the DESCRIPTION of Ip clearly shows the intent of 
the standard developers, even if they cannot mandate that all systems (such as laptops) have 
printers. 

This volume of IEEE Std. 1003.1-200x does not specify what the ownership of the process 
performing the writing to the output device may be. If -c is not used, it is unspecified whether 
the process performing the writing to the output device has permission to read file if there are 
any restrictions in place on who may read file until after it is printed. Also, if -c is not used, the 
results of deleting/;'/<? before it is printed are unspecified. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mailx 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the requirement to associate a unique request ID, and the normal 
generation of a banner page is added. 

• In the OPTIONS section: 

— The -d dest description is expanded, but references to Ipstat are removed. 

— The -m, -o, -s, -t, and -w options are added. 

• In the ENVIRONMENT VARIABLES section, LCJTIME may now affect the execution. 

• The STDOUT section is added. 

The normative text is reworded to avoid use of the term "must" for application requirements. 
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NAME 

Is — list directory contents 

SYNOPSIS 

xsi Is [—CFRacdilqrtul ] [—H | —L ] [—fgmnopsx] [file. . .] 

DESCRIPTION 

For each operand that names a file of a type other than directory or symbolic link to a directory. 
Is shall write the name of the file as well as any requested, associated information. For each 
operand that names a file of type directory. Is shall write the names of files contained within the 
directory as well as any requested, associated information. If one of the -d, -F, or -1 options are 
specified, and one of the -H or -L options are not specified, for each operand that names a file of 
type symbolic link to a directory. Is shall write the name of the file as well as any requested, 
associated information. If none of the -d, -F, or -1 options are specified, or the -H or -L options 
are specified, for each operand that names a file of type symbolic link to a directory. Is shall write 
the names of files contained within the directory as well as any requested, associated 
information. 

If no operands are specified. Is shall write the contents of the current directory. If more than one 
operand is specified. Is shall write non-directory operands first; it shall sort directory and non¬ 
directory operands separately according to the collating sequence in the current locale. 

The Is utility shall detect infinite loops; that is, entering a previously visited directory that is an 
ancestor of the last file encountered. When it detects an infinite loop. Is shall write a diagnostic 
message to standard error and shall either recover its position in the hierarchy or terminate. 

OPTIONS 

The Is utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported: 

-C Write multi-text-column output with entries sorted down the columns, according 

to the collating sequence. The number of text columns and the column separator 
characters are unspecified, but should be adapted to the nature of the output 
device. 

-F Do not follow symbolic links named as operands unless the -H or options are 

specified. Write a slash (' /') immediately after each path name that is a directory, 
an asterisk (' *') after each that is executable, a vertical bar (' |') after each that is 

man a FIFO, and an at sign (' @ ') after each that is a symbolic link. For other file types, 

other symbols may be written. 

-H If a symbolic link referencing a file of type directory is specified on the command 

line. Is shall evaluate the file information and file type to be those of the file 
referenced by the link, and not the link itself; however. Is shall write the name of 
the link itself and not the file referenced by the link. 

-F Evaluate the file information and file type for all symbolic links (whether named 

on the command line or encountered in a file hierarchy) to be those of the file 
referenced by the link, and not the link itself; however. Is shall write the name of 
the link itself and not the file referenced by the link. When -F is used with -1, write 
the contents of symbolic links in the long format (see the STDOUT section). 

-R Recursively list subdirectories encountered. 

-a Write out all directory entries, including those whose names begin with a period 

(' .'). Entries beginning with a period shall not be written out unless explicitly 
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referenced, the -a option is supplied, or an implementation-dependent condition 
shall cause them to be written. 

-c Use time of last modification of the file status information (see <sys/stat.h> in the 

System Interfaces volume of IEEE Std. 1003.1-200x) instead of last modification of 
the file itself for sorting (-t) or writing (-1). 

-d Do not follow symbolic links named as operands unless the -H or -L options are I 

specified. Do not treat directories differently than other types of files. The use of -d I 
with -R produces unspecified results. 

xsi -f Force each argument to be interpreted as a directory and list the name found in 

each slot. This option shall turn off -1, -t, -s, and -r, and shall turn on -a; the order 
is the order in which entries appear in the directory. 

xsi -g The same as -1, except that the owner shall not be written. 

-i For each file, write the file's file serial number (see stat( ) in the System Interfaces 

volume of IEEE Std. 1003.1-200x). 

-1 (The letter ell.) Do not follow symbolic links named as operands unless the -H or I 

-L options are specified. Write out in long format (see the STDOUT section). When I 
-1 (ell) is specified, -1 (one) shall be assumed. I 

xsi -m Stream output format; list files across the page, separated by commas. 

xsi -n The same as -1, except that the owner's UID and GID numbers are written, rather 

than the associated character strings. 

xsi -o The same as -1, except that the group is not written. 

xsi -p Write a slash (' /') after each file name if that file is a directory. 

-q Force each instance of non-printable file name characters and <tab> characters to 

be written as the question-mark (' ?') character. Implementations may provide 
this option by default if the output is to a terminal device. 

-r Reverse the order of the sort to get reverse collating sequence or oldest first. 

xsi -s Indicate the total number of file system blocks consumed by each file displayed. 

The block size is implementation-dependent. 

-t Sort by time modified (most recently modified first) before sorting the operands by 

the collating sequence. 

-u Use time of last access (see <sys/stat.h> in the System Interfaces volume of 

IEEE Std. 1003.1-200x) instead of last modification of the file for sorting (-t) or 
writing (- 1 ). 

xsi -x The same as -C, except that the multi-text-column output is produced with entries 

sorted across, rather than down, the columns. 

-q (The numeric digit one.) Force output to be one entry per line. 

Specifying more than one of the options in the following mutually exclusive pairs shall not be 

xsi considered an error: -C and -1 (ell),-m and -1 (ell), -x and -1 (ell),-C and -1 (one), -H and -L, I 

-c and -u. The last option specified in each pair shall determine the output format. 
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23023 OPERANDS 

23024 The following operand shall be supported: 

23025 file A path name of a file to be written. If the file specified is not found, a diagnostic 

23026 message shall be output on standard error. 

23027 STDIN 

23028 Not used. 

23029 INPUT FILES 

23030 None. 


23031 ENVIRONMENT VARIABLES 

23032 The following environment variables shall affect the execution of Is: 


23033 

23034 

23035 

23036 

23037 

23038 

23039 

23040 


COLUMNS Determine the user's preferred column position width for writing multiple text- 
column output. If this variable contains a string representing a decimal integer, the 
Is utility shall calculate how many path name text columns to write (see -C) based 
on the width provided. If COLUMNS is not set or invalid, an implementation- 
dependent number of column positions shall be assumed, based on the 
implementation's knowledge of the output device. The column width chosen to 
write the names of files in any given directory shall be constant. File names shall 
not be truncated to fit into the multiple text-column output. 


23041 

23042 

23043 

23044 

23045 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


23046 

23047 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


23048 

23049 

23050 


LCJCOLLATE 

Determine the locale for character collation information in determining the path 
name collation sequence. 


23051 

23052 

23053 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments) and which characters are defined as printable (character class print). 


23054 LC_MESSAGES 

23055 Determine the locale that should be used to affect the format and contents of 

23056 diagnostic messages written to standard error. 

23057 LC_TIME Determine the format and contents for date and time strings written by Is. 

23058 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

23059 TZ Determine the timezone for date and time strings written by Is. 

23060 ASYNCHRONOUS EVENTS 

23061 Default. 


23062 STDOUT 

23063 The default format shall be to list one entry per line to standard output; the exceptions are to 

23064 xsi terminals or when one of the -C,-m, or -x options is specified. If the output is to a terminal, the 

23065 format is implementation-dependent. 
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xsi When -m is specified, the format used shall be: 

"%s, %s, <filenamel>, <filename2> 

where the largest number of file names shall be written without exceeding the length of the line. 

If the -i option is specified, the file's file serial number (see <sys/stat.h> in the System Interfaces 
volume of IEEE Std. 1003.1-200x) shall be written in the following format before any other 
output for the corresponding entry: 

%u ", <file serial number> 

If the -1 option is specified without -L, the following information shall be written: I 

"%s %u %s %s %u %s %s\n", <file mode>, <number of links>, 

<owner name>, <group name>, <number of bytes in the file>, 

<date and time>, <pathname> 

If the file is a symbolic link, this information shall be about the link itself and the <pathname> I 
field shall be of the form: I 

"%s —> %s", <pathname of link>, <contents of link> I 

If both -1 and -L are specified, the following information shall be written: I 

"%s %u %s %s %u %s %s0, <file mode>, <number of links>, I 

<owner name >, <group name>, <number of bytes in the file>, I 

<date and time>, <pathname of link> I 

where all fields except <pathname oflink> shall be for the file resolved from the symbolic link. I 

xsi The -g, -n, and -o options use the same format as -1, but with omitted items and their I 
associated <blank> characters. See the OPTIONS section. 

xsi In both the preceding -1 forms. If <owner name> or <gronp name> cannot be determined, or if -n I 
is given, they shall be replaced with their associated numeric values using the format %w. 

The <date and time>, field shall contain the appropriate date and timestamp of when the file was 
last modified. In the POSIX locale, the field shall be the equivalent of the output of the following 
date command: 

date "+%b %e %H:%M" 

if the file has been modified in the last six months, or: 

date "+%b %e %Y" 

(where two <space> characters are used between %e and %Y) if the file has not been modified in 
the last six months or if the modification date is in the future, except that, in both cases, the final 
<newline> character produced by date shall not be included and the output shall be as if the date 
command were executed at the time of the last modification date of the file rather than the 
current time. When the LC_TIME locale category is not set to the POSIX locale, a different format 
and order of presentation of this field may be used. 

If the file is a character special or block special file, the size of the file may be replaced with 
implementation-dependent information associated with the device in question. 

If the path name was specified as a file operand, it shall be written as specified. 

xsi The file mode written under the -1,-g, -n, and -o options shall consist of the following format: 

"%c%s%s%s%c", <entry type>, <owner permissions>, 

<group permissions>, <other permissions>, 
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23114 
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<optional alternate access method flag> 

The <optional alternate access method flag> shall be a single <space> character if there is no 
alternate or additional access control method associated with the file; otherwise, a printable 
character shall be used. 

The <entry type> character shall describe the type of file, as follows: I 

d Directory. I 

b Block special file. 

c Character special file. I 

1 (ell) Symbolic link. I 

p FIFO. 

— Regular file. 

Implementations may add other characters to this list to represent other implementation- 
dependent file types. 

The next three fields shall be three characters each: 

<owner permissions> 

Permissions for the file owner class (see the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 4.1, File Access Permissions). I 

<gronp permissions> 

Permissions for the file group class. 

<other permissions> 

Permissions for the file other class. 

Each field shall have three character positions: 

1. If ' r', the file is readable; if ' - ', the file is not readable. 

2. If ' w', the file is writable; if ' , the file is not writable. 

3. The first of the following that applies: 

S If in <owner permissions>, the file is not executable and set-user-ID mode is set. If in 
<gronp permissions>, the file is not executable and set-group-ID mode is set. 

s If in <owner permissions>, the file is executable and set-user-ID mode is set. If in 
<gronp permissions>, the file is executable and set-group-ID mode is set. 

x The file is executable or the directory is searchable. 

- None of the attributes of ' S', ' s', or ' x' applies. 

Implementations may add other characters to this list for the third character position. Such 
additions shall, however, be written in lowercase if the file is executable or searchable, and 
in uppercase if it is not. 

xsi If any of the -1,-g, -n, -o, or -s options is specified, each list of files within the directory shall be 
preceded by a status line indicating the number of file system blocks occupied by files in the 
directory in 512-byte units, rounded up to the next integral number of units, if necessary. In the 
POSIX locale, the format shall be: 

"total %u\n", <number of units in the directory> 
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If more than one directory, or a combination of non-directory files and directories are written, 
either as a result of specifying multiple operands, or the -R option, each list of files within a 
directory shall be preceded by: 

"\n%s:\n", <directory name> 

If this string is the first thing to be written, the first <newline> character shall not be written. 
This output shall precede the number of units in the directory. 

xsi If the -s option is given, each file shall be written with the number of blocks used by the file. 

Along with -C, —1, -m, or -x, the number and a <space> character shall precede the file name; 
with -g, -1, -n, or -o, they shall precede each line describing a file. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Many implementations use the equal sign (' =') and the at sign (' @') to denote sockets bound to 
the file system and symbolic links, respectively, for the -F option. Similarly, many historical 
implementations use the ' s' character and the ' 1' character to denote sockets and symbolic 
links, respectively, as the entry type characters for the -1 option. 

It is difficult for an application to use every part of the file modes field of Is -1 in a portable 
manner. Certain file types and executable bits are not guaranteed to be exactly as shown, as 
implementations may have extensions. Applications can use this field to pass directly to a user 
printout or prompt, but actions based on its contents should generally be deferred, instead, to 
the test utility. 

The output of Is (with the -1 and related options) contains information that logically could be 
used by utilities such as chmod and touch to restore files to a known state. However, this 
information is presented in a format that cannot be used directly by those utilities or be easily 
translated into a format that can be used. A character has been added to the end of the 
permissions string so that applications at least have an indication that they may be working in 
an area they do not understand instead of assuming that they can translate the permissions 
string into something that can be used. Future issues or related documents may define one or 
more specific characters to be used based on different standard additional or alternative access 
control mechanisms. 

As with many of the utilities that deal with file names, the output of Is for multiple files or in one 
of the long listing formats must be used carefully on systems where file names can contain 
embedded white space. Systems and system administrators should institute policies and user 
training to limit the use of such file names. 
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23190 The number of disk blocks occupied by the file that it reports varies depending on underlying 

23191 file system type, block size units reported, and the method of calculating the number of blocks. 

23192 On some file system types, the number is the actual number of blocks occupied by the file 

23193 (counting indirect blocks and ignoring holes in the file); on others it is calculated based on the 

23194 file size (usually making an allowance for indirect blocks, but ignoring holes). 

23195 EXAMPLES 

23196 An example of a small directory tree being fully listed with Is -laRF a in the POSIX locale: 

23197 total 11 


23198 

drwxr-xr-x 

3 

hi j 

prog 

64 

Jul 

4 

12 : 07 

./ 

23199 

drwxrwxrwx 

4 

hi j 

prog 

3264 

Jul 

4 

12 : 09 

. ./ 

23200 

drwxr-xr-x 

2 

hi j 

prog 

48 

Jul 

4 

12 : 07 

b/ 

23201 

-rwxr—r— 

1 

hi j 

prog 

572 

Jul 

4 

12 : 07 

f oo* 

23202 

a/b: 









23203 

total 4 









23204 

drwxr-xr-x 

2 

hi j 

prog 

48 

Jul 

4 

12 : 07 

./ 

23205 

drwxr-xr-x 

3 

hi j 

prog 

64 

Jul 

4 

12 : 07 

. ./ 

23206 

-rw-r—r— 

1 

hi j 

prog 

700 

Jul 

4 

12 : 07 

bar 


23207 RATIONALE 

23208 Some historical implementations of the Is utility show all entries in a directory except dot and 

23209 dot-dot when a superuser invokes Is without specifying the -a option. When "normal" users 

23210 invoke Is without specifying -a, they should not see information about any files with names 

23211 beginning with period unless they were named as file operands. 

23212 Implementations are expected to traverse arbitrary depths when processing the -R option. The 

23213 only limitation on depth should be based on running out of physical storage for keeping track of 

23214 untraversed directories. 

23215 The -1 (one) option is currently found in BSD and BSD-derived implementations only. It is 

23216 required in this volume of IEEE Std. 1003.1-200x so that portable applications might ensure that 

23217 output is one entry per line, even if the output is to a terminal. 

23218 Generally, this volume of IEEE Std. 1003.1-200x is silent about what happens when options are 

23219 given multiple times. In the cases of -C, — 1 , and -1, however, it does specify the results of these 

23220 overlapping options. Since Is is one of the most aliased commands, it is important that the 

23221 implementation perform intuitively. For example, if the alias were: 

23222 alias ls = "ls -C" 

23223 and the user typed Is -1, single-text-column output should result, not an error. 

23224 The BSD Is provides a -A option (like -a, but dot and dot-dot are not written out). The small 

23225 difference from -a did not seem important enough to require both. 

23226 Implementations are allowed to make -q the default for terminals to prevent trojan horse 

23227 attacks on terminals with special escape sequences. This is not required because: 

23228 • Some control characters may be useful on some terminals; for example, a system might write 

23229 them as " \001" or " "A". 

23230 • Special behavior for terminals is not relevant to application portability. 

23231 An early proposal specified that the optional alternate access method flag had to be ' +' if there 

23232 was an alternate access method used on the file or <space> if there was not. This was changed to 

23233 be <space> if there is not and a single printable character if there is. This was done for three 

23234 reasons: 
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1. There are historical implementations using characters other than ' +'. 

2. There are implementations that vary this character used in that position to distinguish 
between various alternate access methods in use. 

3. The standard developers did not want to preclude futures specifications that might need a 
way to specify more than one alternate access method. 

Nonetheless, implementations providing a single alternate access method are encouraged to use 
' +'. 

In an early proposal, the units used to specify the number of blocks occupied by files in a 
directory in an Is -1 listing was implementation-dependent. This was because BSD systems have 
historically used 1024-byte units and System V systems have historically used 512-byte units. It 
was pointed out by BSD developers that their system has used 512-byte units in some places and 
1024-byte units in other places. (System V has consistently used 512.) Therefore, this volume of 
IEEE Std. 1003.1-200x usually specifies 512. Future releases of BSD are expected to consistently 
provide 512 bytes as a default with a way of specifying 1024-byte units where appropriate. 

The <date and time> field in the -1 format is specified only for the POSIX locale. As noted, the I 
format can be different in other locales. No mechanism for defining this is present in this volume I 
of IEEE Std. 1003.1-200x, as the appropriate vehicle is a messaging system; that is, the format 
should be specified as a "message". 

FUTURE DIRECTIONS 

The -s uses implementation-dependent units and cannot be used portably; it may be withdrawn 
in a future issue. I 

SEE ALSO 

chmod,find, the System Interfaces volume of IEEE Std. 1003.1-200x, <sys/stat.h> 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

Second FUTURE DIRECTION added. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the -F option, other symbols are allowed for other file types. 

Treatment of symbolic links is added, as defined in the IEEE P1003.2b draft standard. 
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23269 NAME 

23270 m4 — macro processor (DEVELOPMENT) 

23271 SYNOPSIS 

23272 xsi m4 [—s] [—D name[=val] ] . . . [—U name] . . . file. . . 

23273 

23274 DESCRIPTION 

23275 The m4 utility is a macro processor that shall read one or more text files, process them according 

23276 to their included macro statements, and write the results to standard output. 

23277 OPTIONS 

23278 The m4 utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

23279 Section 12.2, Utility Syntax Guidelines, except that the order of the -D and -U options shall be I 

23280 significant. 

23281 The following options shall be supported: 

23282 -s Enable line synchronization output for the c89 preprocessor phase (that is, Mine 

23283 directives). 

23284 -D mme[=val] 

23285 Define name to val or to null if =val is omitted. 

23286 -U name Undefine name. 


23287 OPERANDS 

23288 The following operand shall be supported: 

23289 file A path name of a text file to be processed. If no file is given, or if it is the 

23290 standard input shall be read. 

23291 STDIN 

23292 The standard input shall be a text file that is used if no file operand is given, or if it is ' . 

23293 INPUT FILES 

23294 The input file named by the file operand shall be a text file. 


23295 ENVIRONMENT VARIABLES 

23296 The following environment variables shall affect the execution of m4: 

23297 

23298 

23299 

23300 

23301 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

23302 

23303 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

23304 

23305 

23306 

LCJCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

23307 

23308 

23309 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

23310 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 
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ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall be the same as the input files, after being processed for macro 
expansion. 

STDERR 

Used to display strings with the errprint macro, macro tracing enabled by the traceon macro, the 
defined text for macros written by the dumpdef macro, or for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

The m4 utility shall compare each token from the input against the set of built-in and user- 
defined macros. If the token matches the name of a macro, then the token shall be replaced by 
the macros defining text, if any, and rescanned for matching macro names. Once no portion of 
the token matches the name of a macro, it shall be written to standard output. Macros may have 
arguments, in which case the arguments shall be substituted into the defining text before it is 
rescanned. 

Macro calls have the form: 

name(argl, arg2, ..., argn) 

Macro names shall consist of letters, digits, and underscores, where the first character is not a 
digit. Tokens not of this form shall not be treated as macro names. 

The application shall ensure that the left parenthesis immediately follows the name of the I 
macro. If a token matching the name of a macro is not followed by a left parenthesis, it is I 
handled as a use of that macro without arguments. I 

If a macro name is followed by a left parenthesis, its arguments are the comma-separated tokens 
between the left parenthesis and the matching right parenthesis. Unquoted <blank> and 
<newline> characters preceding each argument shall be ignored. All other characters, including 
trailing <blank> and <newline> characters, are retained. Commas enclosed between left and 
right parenthesis characters do not delimit arguments. 

Arguments are positionally defined and referenced. The string " $1" in the defining text shall be 
replaced by the first argument. Systems shall support at least nine arguments; only the first nine 
can be referenced, using the strings "$1" to "$9", inclusive. The string "$0" is replaced with 
the name of the macro. The string " $ #" is replaced by the number of arguments as a string. The 
string " $ *" is replaced by a list of all of the arguments, separated by commas. The string " $ @" 
is replaced by a list of all of the arguments separated by commas, and each argument is quoted 
using the current left and right quoting strings. 

If fewer arguments are supplied than are in the macro definition, the omitted arguments are 
taken to be null. It is not an error if more arguments are supplied than are in the macro 
definition. 

No special meaning is given to any characters enclosed between matching left and right quoting 
strings, but the quoting strings are themselves discarded. By default, the left quoting string 
consists of a grave accent (' '') and the right quoting string consists of an acute accent (' ' ') see 
also the changequote macro. 

Comments are written but not scanned for matching macro names; by default, the begin- 
comment string consists of the number sign character and the end-comment string consists of a 
<newline> character. See also the changecom and dnl macros. 
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The m4 utility makes available the following built-in macros. They can be redefined, but once 
this is done the original meaning is lost. Their values are null unless otherwise stated. In the 
descriptions below, the term defining text refers to the value of the macro: the second argument 
to the define macro, among other things. 

changecom The changecom macro sets the begin-comment and end-comment strings. With no 
arguments, the comment mechanism is disabled. With a single argument, that 
argument becomes the begin-comment string and the <newline> character 
becomes the end-comment string. With two arguments, the first argument 
becomes the begin-comment string and the second argument becomes the end- 
comment string. Systems support comment strings of at least five characters. 

changequote The changequote macro sets the begin-quote and end-quote strings. With no 
arguments, the quote strings are set to the default values (that is, ' '). With a 
single argument, that argument becomes the begin-quote string and the <newline> 
character becomes the end-quote string. With two arguments, the first argument 
becomes the begin-quote string and the second argument becomes the end-quote 
string. Systems support quote strings of at least five characters. 

deer The defining text of the deer macro is its first argument decremented by 1. It is an 

error to specify an argument containing any non-numeric characters. 


23375 Notes to Reviewers 


This section with side shading will not appear in the final copy. - Ed. 

Re Dl, XCU, ERN 285: What base is this sort of arithmetic performed in: decimal, 
octal, or what? (Same for incr, eval, etc.) Is the output base retained? 

define The second argument is specified as the defining text of the macro whose name is 

the first argument. 

defn The defining text of the defn macro is the quoted definition (using the current 

quoting strings) of its arguments. 

divert The m4 utility maintains ten temporary buffers, numbered 0 to 9, inclusive. 


23384 Notes to Reviewers 


divnum 


This section with side shading will not appear in the final copy. - Ed. 

Re Dl, XCU, ERN 286: Buffer 0 seems strange: it's one of the 10 buffers, and thus 
should be a diversion buffer, but at 19704 it implies that it's the name of the main 
output. What is it (or are there really only 9 diversion buffers?) Also, see austin- 
group mail sequence #295. 

When the last of the input has been processed, any output that has been placed in 
these buffers is written to standard output in buffer-numerical order. The divert 
macro diverts future output to the buffer specified by its argument. Specifying no 
argument or an argument of 0 resumes the normal output process. Output 
diverted to a stream other than 0 to 9 is discarded. It is an error to specify an 
argument containing any non-numeric characters. 

The defining text of the divnum macro is the number of the current output stream 
as a string. 

The dnl macro shall cause m4 to discard all input characters up to and including 
the next <newline> character. 
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23400 

23401 

dumpdef 

The dumpdef macro writes the defined text to standard error for each of the 
macros specified as arguments, or, if no arguments are specified, for all macros. 

23402 

errprint 

The errprint macro writes its arguments to standard error. 

23403 

23404 

23405 

23406 

23407 

23408 

23409 

23410 

23411 

eval 

The eval macro evaluates its first argument as an arithmetic expression, using 32- 
bit signed integer arithmetic. All of the C-language operators are supported, except 
for " [ ] ", "++", "—", (type), unary ' *', sizeof, ' , ', ' .', " ? :' &', and 

all assignment operators. It is an error to specify any of these operators. Precedence 
and associativity are as in C. Systems support octal and hexadecimal numbers as 
in C. The second argument, if specified, sets the radix for the result; the default is 
10. The third argument, if specified, sets the minimum number of digits in the 
result. It is an error to specify the second or third argument containing any non¬ 
numeric characters. 

23412 

23413 

23414 

ifdef 

If the first argument to the ifdef macro is defined, the defining text is the second 
argument. Otherwise, the defining text is the third argument, if specified, or the 
null string, if not. 

23415 

23416 

23417 

23418 

ifelse 

If the first argument (or the defining text of the first argument if it is a macro 
name) to the ifelse macro is the same as the second argument (or the defining text 
of the second argument if it is a macro name), then the defining text is the third 
argument. 

23419 Notes to Reviewers 

23420 This section with side shading will not appear in the final copy. - Ed. 

23421 Dl, XCU, ERN 287 (as modified by email #297) suggests the following replacement 

23422 text for ifelse: "This function takes 3n+0 or 3n+l arguments. For each group of 3 

23423 arguments, if the first and second are the same, the result is the third of the group. 

23424 If the strings are not equal, and no arguments remain, the defining text is null. If 

23425 one argument remains, it becomes the defining text. If three or more arguments 

23426 remain, the process is repeated with the new group of three arguments. If 3n+2 

23427 arguments are provided, the evaluation proceeds as above, but a warning is 

23428 generated and the last argument ignored. 

23429 If there are more than four arguments, the initial comparison of the first and 

23430 second arguments are repeated for each group of three arguments. If no match is 

23431 found, the defining text is the argument following the last set of three compared; 

23432 otherwise, it is null. 

23433 

23434 

include 

The defining text for the include macro is the contents of the file named by the first 
argument. It is an error if the file cannot be read. 

23435 

23436 

incr 

The defining text of the incr macro is its first argument incremented by 1. It is an 
error to specify an argument containing any non-numeric characters. 

23437 

23438 

23439 

23440 

index 

The defining text of the index macro is the first character position (as a string) in 
the first argument where a string matching the second argument begins (zero 
origin), or 

-1 if the second argument does not occur. 

23441 

len 

The defining text of the len macro is the length (as a string) of the first argument. 

23442 

23443 

23444 

m4exit 

Exit from the m4 utility. If the first argument is specified, it is the exit code. The 
default is zero. It is an error to specify an argument containing any non-numeric 
characters. 
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23445 

23446 

23447 

mlwrap 

The first argument is processed when EOF is reached. If the m4wrap macro is used 
multiple times, the arguments specified are processed in the order in which the 
m4wrap macros were processed. 

23448 

23449 

maketemp 

The defining text is the first argument, with any trailing ' X' characters replaced 
with the current process ID as a string. 

23450 

23451 

popdef 

The popdef macro deletes the current definition of its arguments, replacing it with 
the previous one. If there is no previous definition, the macro is undefined. 

23452 

23453 

pushdef 

The pushdef macro is identical to the define macro with the exception that it 
preserves any current definition for future retrieval using the popdef macro. 

23454 

shift 

The defining text for the shift macro is all of its arguments except for the first one. 

23455 

23456 

sin elude 

The sinclude macro is identical to the include macro, except that it is not an error 
if the file is inaccessible. 

23457 

23458 

23459 

23460 

23461 

23462 

23463 

substr 

The defining text for the substr macro is the substring of the first argument 
beginning at the zero-offset character position specified by the second argument. 
The third argument, if specified, is the number of characters to select; if not 
specified, the characters from the starting point to the end of the first argument 
become the defining text. It is not an error to specify a starting point beyond the 
end of the first argument and the defining text is null. It is an error to specify an 
argument containing any non-numeric characters. 

23464 

23465 

23466 

23467 

sysemd 

The sysemd macro interprets its first argument as a shell command line. The 
defining text is the string result of that command. No output redirection is 
performed by the m4 utility. The exit status value from the command can be 
retrieved using the sysval macro. 

23468 

23469 

sysval 

The defining text of the sysval macro is the exit value of the utility last invoked by 
the sysemd macro (as a string). 

23470 

23471 

23472 

traceon 

The traceon macro enables tracing for the macros specified as arguments, or, if no 
arguments are specified, for all macros. The trace output is written to standard 
error in an unspecified format. 

23473 

23474 

traceoff 

The traceoff macro disables tracing for the macros specified as arguments, or, if no 
arguments are specified, for all macros. 

23475 

23476 

23477 

translit 

The defining text of the translit macro is the first argument with every character 
that occurs in the second argument replaced with the corresponding character 
from the third argument. 

23478 

23479 

undefine 

The undefine macro deletes all definitions (including those preserved using the 
pushdef macro) of the macros named by its arguments. 

23480 

23481 

23482 

23483 

23484 

un divert 

The undivert macro shall cause immediate output of any text in temporary buffers 
named as arguments, or all temporary buffers if no arguments are specified. 
Buffers can be undiverted into other temporary buffers. Undiverting discards the 
contents of the temporary buffer. It is an error to specify an argument containing 
any non-numeric characters. 

23485 EXIT STATUS 

23486 The following exit values shall be returned: 

23487 

0 Successful completion. 
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23488 >0 An error occurred 

23489 If the m4exit macro is used, the exit value can be specified by the input file. 

23490 CONSEQUENCES OF ERRORS 

23491 Default. 

23492 APPLICATION USAGE 

23493 The defn macro is useful for renaming macros, especially built-ins. 

23494 EXAMPLES 

23495 An example of a single m4 input file capable of generating two output files follows. The file 

23496 filel.m4 could contain lines such as: 

23497 if (VER, 1, do_something) 

23498 if (VER, 2, do_something) 

23499 The makefile for the program might include: 

23500 filel.l.c : filel.m4 

23501 m4 —D VER=1 filel.m4 > filel.l.c 

23502 

23503 filel.2.c : filel.m4 

23504 m4 —D VER=2 filel.m4 > filel.2.c 

23505 

23506 The -U option can be used to undefine VER. If filel.m4 contains: 

23507 if (VER, 1, do_something) 

23508 if (VER, 2, do_something) 

23509 ifndef (VER, do_something) 

23510 then the makefile would contain: 

23511 filel. O.c : filel.m4 

23512 m4 —U VER filel.m4 > filel. O.c 

23513 

23514 filel.l.c : filel.m4 

23515 m4 —D VER=1 filel.m4 > filel.l.c 

23516 

23517 filel. 2. c : filel.m4 

23518 m4 -D VER=2 filel.m4 > filel. 2. c 

23519 

23520 RATIONALE 

23521 None. 

23522 FUTURE DIRECTIONS 

23523 None. 

23524 SEE ALSO 

23525 c89 

23526 CHANGE HISTORY 

23527 First released in Issue 2. 

23528 Issue 4 

23529 Format reorganized. 

23530 Utility Syntax Guideline support mandated. 
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23534 

23535 

23536 

23537 

23538 

23539 

23540 

23541 
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Internationalized environment variable support mandated. 

Issue 5 

The phrase "the defined text for macros written by the dumpdef macro" is added to the 
description of STDERR, and the description of dumpdef is updated to indicate that output is 
written to standard error. The description of eval is updated to indicate that the list of excluded 
C operators excludes unary ' &' and ' . In the description of ifdef, the phrase "and it is not 

defined to be zero" is deleted. 


Issue 6 

In the EXTENDED DESCRIPTION, the eval text is updated to include a ' &' character in the 
excepted list. 

The normative text is reworded to avoid use of the term "must" for application requirements. 
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23542 NAME 

23543 mailx — process messages 

23544 SYNOPSIS 

23545 Send Mode 

23546 mailx [—s subject ] address... 

23547 Receive Mode 

23548 mailx —e 

23549 man mailx [—HiNn] [—F] [—u user] 

23550 man mailx — f [— HiNn] [— F] [file] 

23551 DESCRIPTION 

23552 The mailx utility provides a message sending and receiving facility. It has two major modes, 

23553 selected by the options used: Send Mode and Receive Mode. 

23554 On systems that do not support the User Portability Utilities option, an application using mailx 

23555 shall have the ability to send messages in an unspecified manner (Send Mode). Unless the first 

23556 character of one or more lines is tilde (' ~'), all characters in the input message shall appear in 

23557 the delivered message, but additional characters may be inserted in the message before it is 

23558 retrieved. 

23559 On systems supporting the User Portability Utilities option, mail-receiving capabilities and other 

23560 interactive features. Receive Mode, described below, also shall be enabled. 

23561 Send Mode 

23562 Send Mode can be used by applications or users to send messages from the text in standard 

23563 input. 

23564 Receive Mode 

23565 Receive Mode is more oriented to interactive users. Mail can be read and sent in this interactive 

23566 mode. 

23567 When reading mail, mailx provides commands to facilitate saving, deleting, and responding to 

23568 messages. When sending mail, mailx allows editing, reviewing, and other modification of the 

23569 message as it is entered. 

23570 Incoming mail shall be stored in one or more unspecified locations for each user, collectively 

23571 called the system mailbox for that user. When mailx is invoked in Receive Mode, the system 

23572 mailbox shall be the default place to find new mail. As messages are read, they shall be marked 

23573 to be moved to a secondary file for storage, unless specific action is taken. This secondary file is 

23574 called the mbox and is normally located in the directory referred to by the HOME environment 

23575 variable (see MBOX in the ENVIRONMENT VARIABLES section for a description of this file). 

23576 Messages shall remain in this file until explicitly removed. When the -f option is used to read 

23577 mail messages from secondary files, messages shall be retained in those files unless specifically 

23578 removed. All three of these locations—system mailbox, mbox, and secondary file—are referred 

23579 to in this section as simply "mailboxes", unless more specific identification is required. 
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23580 

23581 

23582 

23583 

23584 

23585 

23586 

23587 

23588 

23589 

23590 

23591 

23592 

23593 

23594 

23595 

23596 

23597 

23598 

23599 

23600 

23601 

23602 

23603 

23604 

23605 

23606 

23607 

23608 

23609 

23610 

23611 

23612 

23613 

23614 

23615 

23616 

23617 

23618 

23619 

23620 

23621 

23622 


OPTIONS 

The mailx utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported. (Only the -s subject option shall be required on all 
systems. The other options are required only on systems supporting the User Portability Utilities 
option.) 

-e Test for the presence of mail in the system mailbox. The mailx utility shall write 

nothing and exit with a successful return code if there is mail to read. 

- Read messages from the file named by the file operand instead of the system 

mailbox. (See also folder.) If no file operand is specified, read messages from the 
mbox instead of the system mailbox. 

man -F Record the message in a file named after the first recipient. The name is the login- 

name portion of the address found first on the To: line in the mail header. 
Overrides the record variable, if set (see Internal Variables in mailx on page 626.) 

-H Write a header summary only. 

-i Ignore interrupts. (See also ignore). 

-n Do not initialize from the system default start-up file. See the EXTENDED 

DESCRIPTION section. 


-N Do not write an initial header summary. 

-s subject Set the Subject header field to subject. All characters in the subject string shall 
appear in the delivered message. The results are unspecified if subject is longer 
than |LINE_MAX} - 10 bytes or contains a <newline> character. 

-u user Read the system mailbox of the login name user. This shall only be successful if 
the invoking user has the appropriate privileges to read the system mailbox of that 
user. 


OPERANDS 

The following operands shall be supported: 

address Addressee of message. When -n is specified and no user start-up files are accessed 

(see the EXTENDED DESCRIPTION section), the user or application shall ensure 
this is an address to pass to the mail delivery system. Any system or user start-up 
files may enable aliases (see alias under Commands in mailx on page 629) that 
may modify the form of address before it is passed to the mail delivery system. 

file A path name of a file to be read instead of the system mailbox when -f is specified. 

The meaning of the file option-argument shall be affected by the contents of the 
folder internal variable; see Internal Variables in mailx on page 626. 

STDIN 

When mailx is invoked in Send Mode (the first synopsis line), standard input shall be the 
message to be delivered to the specified addresses. When in Receive Mode, user commands are 
accepted from stdin. If the User Portability Utilities option is not supported, standard input lines 
beginning with a tilde (' ~') character produce unspecified results. 

If the User Portability Utilities option is supported, then in both Send and Receive Modes, 
standard input lines beginning with the escape character (usually tilde (' ~')) affect processing 
as described in Command Escapes in mailx on page 637. 
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23623 INPUT FILES 

23624 When mailx is used as described by this volume of IEEE Std. 1003.1-200x, the file option- 

23625 argument (see the -f option) and the mb ox shall be text files containing mail messages, 

23626 formatted as described in the OUTPUT FILES section. The nature of the system mailbox is 

23627 unspecified; it need not be a file. 


23628 ENVIRONMENT VARIABLES 

23629 The following environment variables shall affect the execution of mailx: 


23630 

23631 

23632 

23633 

23634 


DEAD Determine the path name of the file in which to save partial messages in case of 

interrupts or delivery errors. The default shall be dead.letter in the directory 
named by the HOME variable. The behavior of mailx in saving partial messages is 
unspecified if the User Portability Utilities option is not supported and DEAD is 
not defined with the value /dev/null. 


23635 

23636 

23637 XSI 

23638 


EDITOR Determine the name of a utility to invoke when the edit (see Commands in mailx 
on page 629) or ~e (see Command Escapes in mailx on page 637) command is 
used. The default editor is ed. The effects of this variable are unspecified if the User 
Portability Utilities option is not supported. 


23639 

23640 

23641 

23642 

23643 

23644 


HOME Determine the path name of the useds home directory. 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


23645 

23646 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


23647 LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

23648 characters (for example, single-byte as opposed to multi-byte characters in 

23649 arguments and input files) and the handling of case-insensitive address and 

23650 header-field comparisons. 


23651 

23652 

23653 

23654 

23655 


LC_TIME Determine the format and contents of the date and time strings written by mailx. 
LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 


23656 

23657 

23658 

23659 

23660 

23661 


LISTER Determine a string representing the command for writing the contents of the 
folder directory to standard output when the folders command is given (see 
folders in Commands in mailx on page 629). Any string acceptable as a 
command_string operand to the sh -c command shall be valid. If this variable is null 
or not set, the output command shall be Is. The effects of this variable are 
unspecified if the User Portability Utilities option is not supported. 


23662 

23663 

23664 

23665 


MAILRC Determine the path name of the start-up file. The default shall be .mailrc in the 
directory referred to by the HOME environment variable. The behavior of mailx is 
unspecified if the User Portability Utilities option is not supported and MAILRC is 
not defined with the value /dev/null. 


23666 

23667 

23668 


MB OX Determine a path name of the file to save messages from the system mailbox that 
have been read. The exit command shall override this function, as shall saving the 
message explicitly in another file. The default shall be mbox in the directory 
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23669 named by the HOME variable. The effects of this variable are unspecified if the 

23670 User Portability Utilities option is not supported. 


23671 XSI 

23672 

23673 

23674 

23675 

23676 

23677 

23678 

23679 

23680 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PAGER Determine a string representing an output filtering or pagination command for 
writing the output to the terminal. Any string acceptable as a command_string 
operand to the sh -c command shall be valid. When standard output is a terminal 
device, the message output shall be piped through the command if the mailx 
internal variable crt is set to a value less the number of lines in the message; see 
Internal Variables in mailx on page 626. If the PAGER variable is null or not set, 
the paginator shall be either more or another paginator utility documented in the 
system documentation. The effects of this variable are unspecified if the User 
Portability Utilities option is not supported. 


23681 

23682 

23683 


SHELL Determine the name of a preferred command interpreter. The default shall be sh. 

The effects of this variable are unspecified if the User Portability Utilities option is 
not supported. 


23684 

23685 

23686 

23687 

23688 


TERM Determine the name of the terminal type, to indicate in an unspecified manner, if 

the internal variable screen is not specified, the number of lines in a screenful of 
headers. If TERM is not set or is set to null, an unspecified default terminal type 
shall be used and the value of a screenful is unspecified. The effects of this variable 
are unspecified if the User Portability Utilities option is not supported. 


23689 

23690 

23691 

23692 

23693 


VISUAL Determine a path name of a utility to invoke when the visual command (see 
Commands in mailx on page 629) or ~v command-escape (see Command Escapes 
in mailx on page 637) is used. If this variable is null or not set, the full-screen 
editor shall be vi. The effects of this variable are unspecified if the User Portability 
Utilities option is not supported. 


23694 ASYNCHRONOUS EVENTS 

23695 When mailx is in Send Mode and standard input is not a terminal, it shall take the standard 

23696 action for all signals. 

23697 In Receive Mode, or in Send Mode when standard input is a terminal, if a SIGINT signal is 

23698 received: 


23699 1. If in command mode, the current command, if there is one, shall be aborted, and a 

23700 command-mode prompt shall be written. 


23701 


2. If in input mode: 


23702 

23703 


a. If ignore is set, mailx shall write " @ \ n", discard the current input line, and continue 
processing, bypassing the message-abort mechanism described in item 2b. 


23704 

23705 

23706 

23707 

23708 

23709 


b. If the interrupt was received while sending mail, either when in Receive Mode or in 
Send Mode, a message shall be written, and another subsequent interrupt, with no 
other intervening characters typed, shall be required to abort the mail message. If in 
Receive Mode and another interrupt is received, a command-mode prompt shall be 
written. If in Send Mode and another interrupt is received, mailx shall terminate with 
a non-zero status. 


23710 


In both cases listed in item b, if the message is not empty: 


23711 

23712 

23713 


i. If save is enabled and the file named by DEAD can be created, the message 
shall be written to the file named by DEAD. If the file exists, the message shall 
be written to replace the contents of the file. 
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23714 ii. If save is not enabled, or the file named by DEAD cannot be created, the 

23715 message shall not be saved. 

23716 The mailx utility shall take the standard action for all other signals. 

23717 STDOUT 

23718 In command and input modes, all output, including prompts and messages, shall be written to 

23719 standard output. 

23720 STDERR 

23721 Used only for diagnostic messages. 

23722 OUTPUT FILES 

23723 Various mailx commands and command escapes can create or add to files, including the mbox, 

23724 the dead-letter file, and secondary mailboxes. When mailx is used as described in this volume of 

23725 IEEE Std. 1003.1-200x, these files shall be text files, formatted as follows: 

23726 line beginning with From<space> 

23727 [one or more header-lines', see Commands in mailx on page 629] 

23728 empty line 

23729 [zero or more body lines 

23730 empty line] 

23731 [line beginning with From<space>. . . ] 

23732 where each message begins with the From <space> line shown, preceded by the beginning of 

23733 the file or an empty line. (The From <space> line is considered to be part of the message header, 

23734 but not one of the header-lines referred to in Commands in mailx on page 629; thus, it shall not 

23735 be affected by the discard, ignore, or retain commands.) The formats of the remainder of the 

23736 From <space> line and any additional header lines are unspecified, except that none shall be 

23737 empty. The format of a message body line is also unspecified, except that no line following an 

23738 empty line shall start with From <space>; mailx shall modify any such user-entered message 

23739 body lines (following an empty line and beginning with From <space>) by adding one or more 

23740 characters to precede the ' F'; it may add these characters to From <space> lines that are not 

23741 preceded by an empty line. 

23742 When a message from the system mailbox or entered by the user is not a text file, it is 

23743 implementation-dependent how such a message is stored in files written by mailx. 

23744 EXTENDED DESCRIPTION 

23745 The entire Extended Description section shall apply only to implementations supporting the 

23746 User Portability Utilities option. 

23747 The mailx utility cannot guarantee support for all character encodings in all circumstances. For 

23748 example, inter-system mail may be restricted to 7-bit data by the underlying network, 8-bit data 

23749 need not be portable to non-intemationalized systems, and so on. Under these circumstances, it 

23750 is recommended that only characters defined in the ISO/IEC 646:1991 standard International 

23751 Reference Version (equivalent to ASCII) 7-bit range of characters be used. 

23752 When mailx is invoked using one of the Receive Mode synopsis forms, it shall write a page of 

23753 header-summary lines (if -N was not specified and there are messages, see below), followed by 

23754 a prompt indicating that mailx can accept regular commands (see Commands in mailx on page 

23755 6 29); this is termed command mode. The page of header-summary lines shall contain the first new 

23756 message if there are new messages, or the first unread message if there are unread messages, or 

23757 the first message. When mailx is invoked using the Send Mode synopsis and standard input is a 

23758 terminal, if no subject is specified on the command line and the asksub variable is set, a prompt 

23759 for the subject shall be written. At this point, mailx is in input mode. This input mode is also 

23760 entered when using one of the Receive Mode synopsis forms and a reply or new message is 
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23761 

23762 

23763 

23764 

23765 

23766 

23767 

23768 

23769 

23770 

23771 

23772 

23773 

23774 

23775 

23776 

23777 

23778 

23779 

23780 

23781 

23782 

23783 

23784 

23785 

23786 

23787 

23788 

23789 

23790 

23791 

23792 

23793 

23794 

23795 

23796 

23797 

23798 

23799 

23800 

23801 

23802 

23803 

23804 

23805 

23806 


composed using the reply. Reply, followup. Followup, or mail commands and standard input 
is a terminal. When the message is typed and the end of message is encountered, the message 
shall be passed to the mail delivery software. Commands can be entered by beginning a line 
with the escape character (by default, tilde (' "')) followed by a single command letter and 
optional arguments. See Commands in mailx on page 629 for a summary of these commands. It 
is unspecified what effect these commands will have if standard input is not a terminal when a 
message is entered using either the Send Mode synopsis, or the Read Mode commands reply. 
Reply, followup. Followup, or mail. 

Note: For notational convenience, this section uses the default escape character, tilde, in all 

references and examples. 

At any time, the behavior of mailx shall be governed by a set of environmental and internal 
variables. These are flags and valued parameters that can be set and cleared via the mailx set 
and unset commands. 

Regular commands are of the form: 

[ command ] [ msglist ] [argument ...] 

If no command is specified in command mode, next shall be assumed. In input mode, commands I 
shall be recognized by the escape character, and lines not treated as commands shall be taken as 
input for the message. 

In command mode, each message shall be assigned a sequential number, starting with 1. 

All messages have a state that affects how they are displayed in the header summary and how 
they are retained or deleted upon termination of mailx. There is at any time the notion of a 
current message, marked by a ' >' at the beginning of a line in the header summary. When mailx I 
is invoked using one of the Receive Mode synopsis forms, the current message shall be the first I 
new message, if there is a new message, or the first unread message if there is an unread I 
message, or the first message if there are any messages, or unspecified if there are no messages I 
in the mailbox. Each command that takes an optional list of messages ( msglist ) or an optional I 
single message ( message ) on which to operate shall leave the current message set to the highest- I 
numbered message of the messages specified, unless the command deletes messages, in which I 
case the current message shall be set to the first undeleted message (that is, a message not in the I 
deleted state) after the highest-numbered message deleted by the command, if one exists, or the I 
first undeleted message before the highest-numbered message deleted by the command, if one I 
exists, or to an unspecified value if there are no remaining undeleted messages. All messages are I 
in one of the following states: I 

new The message is present in the system mailbox and has not been viewed by the user 

or moved to any other state. Messages in state new when mailx quits shall be 
retained in the system mailbox. 

unread The message has been present in the system mailbox for more than one invocation 

of mailx and has not been viewed by the user or moved to any other state. 
Messages in state unread when mailx quits shall be retained in the system mailbox. 

read The message has been processed by one of the following commands: ~f, ~m, ~F, ~M, 

copy, mbox, next, pipe, print. Print, top, type. Type, undelete. The delete, dp, and 
dt commands may also cause the next message to be marked as read, depending on 
the value of the autoprint variable. Messages that are in the system mailbox and in 
state read when mailx quits shall be saved in the mbox, unless the internal variable 
hold was set. Messages that are in the mbox or in a secondary mailbox and in state 
read when mailx quits shall be retained in their current location. 
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The message has been processed by one of the following commands: delete, dp, 
dt. Messages in state deleted when mailx quits shall be deleted. Deleted messages I 
shall be ignored until mailx quits or changes mailboxes or they are specified to the I 
undelete command; for example, the message specification / string shall only I 
search the subject lines of messages that have not yet been deleted, unless the I 
command operating on the list of messages is undelete. No deleted message or I 
deleted message header shall be displayed by any mailx command other than I 
undelete. I 

The message has been processed by a preserve command. When mailx quits, the 
message shall be retained in its current location. I 

The message has been processed by one of the following commands: save or I 
write. If the current mailbox is the system mailbox, and the internal variable I 
keepsave is set, messages in the state saved shall be saved to the file designated by I 
the MB OX variable (see the ENVIRONMENT VARIABLES section). If the current I 
mailbox is the system mailbox, messages in the state saved shall be deleted from I 
the current mailbox, when the quit or file command is used to exit the current I 
mailbox. I 

The header-summary line for each message shall indicate the state of the message. 

Many commands take an optional list of messages ( msglist) on which to operate, which defaults 
to the current message. A msglist is a list of message specifications separated by <blank> 
characters, which can include: 

n Message number n. 

+ The next undeleted message, or the next deleted message for the undelete command. 

- The next previous undeleted message, or the next previous deleted message for the 

undelete command. 

The current message. 

A The first undeleted message, or the first deleted message for the undelete command. 

$ The last message. 

* All messages. 

n-m An inclusive range of message numbers. 

address All messages from address; any address as shown in a header summary shall be 
matchable in this form. 

/string All messages with string in the subject line (case ignored). 

: c All messages of type c, where c shall be one of: I 

d Deleted messages, 
n New messages. 

o Old messages (any not in state read or new), 
r Read messages, 
u Unread messages. 

Other commands take an optional message ( message ) on which to operate, which defaults to the 
current message. All of the forms allowed for msglist are also allowed for message, but if more 
than one message is specified, only the first shall be operated on. 


deleted 

preserved 

saved 
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Other arguments are usually arbitrary strings whose usage depends on the command involved. 

Start-Up in mailx 

At start-up time, mailx shall take the following steps in sequence: 

1. Establish all variables at their stated default values. 

2. Process command line options, overriding corresponding default values. 

3. Import any of the DEAD, EDITOR , MBOX, LISTER , PAGER , SHELL , or VISUAL variables 
that are present in the environment, overriding the corresponding default values. 

4. Read mailx commands from an unspecified system start-up file, unless the -n option is 
given, to initialize any internal mailx variables and aliases. 

5. Process the start-up file of mailx commands named in the user MAILRC variable. 

Most regular mailx commands are valid inside start-up files, the most common use being to set 
up initial display options and alias lists. The following commands shall be invalid in the start-up 
man file: !, edit, hold, mail, preserve, reply. Reply, shell, visual,Copy, followup, and Followup. Any 
errors in the start-up file shall either cause mailx to terminate with a diagnostic message and a 
non-zero status or to continue after writing a diagnostic message, ignoring the remainder of the 
lines in the start-up file. 

A blank line in a start-up file shall be ignored. 

Internal Variables in mailx 

The following variables are internal mailx variables. Each internal variable can be set via the 
mailx set command at any time. The unset and set no name commands can be used to erase 
variables. 

In the following list, variables shown as: 

variable 

represent Boolean values. Variables shown as: 

variable =value 

shall be assigned string or numeric values. For string values, the rules in Commands in mailx on 
page 629 concerning file names and quoting also apply. 

The defaults specified here may be changed by the implementation-dependent system start-up 
file unless the user specifies the -n option. 

man allnet All network names whose login name components match are treated as identical. 

This shall cause the msglist message specifications to behave similarly. The default 
shall be noallnet. See also the alternates command and the metoo variable. 

append Append messages to the end of the mbox file upon termination instead of placing 
them at the beginning. The default shall be noappend. This variable shall not 
affect the save command when saving to the mbox. 

ask, asksub 

Prompt for a subject line on outgoing mail if one is not specified on the command 
line with the -s option. The ask and asksub forms are synonyms; the system shall 
refer to asksub and no asksub in its messages, but shall accept ask and no ask as 
user input to mean asksub and no asksub. It shall not be possible to set both ask 
and no asksub, or no ask and asksub. The default shall be asksub, but no 
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prompting shall be done if standard input is not a terminal. 

23891 

askbcc 

Prompt for the blind copy list. The default shall be noaskbcc. 

23892 

askcc 

Prompt for the copy list. The default shall be noaskcc. 

23893 

23894 

autoprint 

Enable automatic writing of messages after delete and undelete commands. The 
default shall be no autoprint. 

23895 

23896 

23897 

23898 

bang 

Enable the special-case treatment of exclamation-marks (' !') in escape command 
lines; see the escape command and Command Escapes in mailx on page 637. The 
default shall be nobang, disabling the expansion of ' !' in the command argument 
to the ~! command and the ~<\command escape. 

23899 

23900 

23901 

cmd =command 

Set the default command to be invoked by the pipe command. The default shall be 

nocmd. 

23902 

23903 

23904 

crt -number 

Pipe messages having more than number lines through the command specified by 
the value of the PAGER variable. The default shall be nocrt. If it is set to null, the 
value used is implementation-dependent. 

23905 XSI 

23906 

debug 

Enable verbose diagnostics for debugging. Messages are not delivered. The 
default shall be no debug. 

23907 

23908 

23909 

23910 

dot 

When dot is set, a period on a line by itself during message input from a terminal 
shall also signify end-of-file (in addition to normal end-of-file). The default shall be 
nodot. If ignoreeof is set (see below), a setting of nodot shall be ignored and the 
period is the only method to terminate input mode. 

23911 

23912 

23913 

escapes 

Set the command escape character to be the character ' c '. By default, the 
command escape character shall be tilde. If escape is unset, tilde shall be used; if it 
is set to null, command escaping shall be disabled. 

23914 

flipr 

Reverse the meanings of the R and r commands. The default shall be noflipr. 

23915 

23916 

23917 

23918 

23919 

23920 

23921 

23922 

23923 

folder =directory 

The default directory for saving mail files. User-specified file names beginning 
with a plus sign (' +') shall be expanded by preceding the file name with this 
directory name to obtain the real path name. If directory does not start with a slash 
(' /'), the contents of HOME shall be prefixed to it. The default shall be nofolder. 
If folder is unset or set to null, user-specified file names beginning with ' +' shall 
refer to files in the current directory that begin with the literal ' +' character. See 
also outfolder below. The folder value need not affect the processing of the files 
named in MB OX and DEAD. 

23924 

23925 

header 

Enable writing of the header summary when entering mailx in Receive Mode. The 
default shall be header. 

23926 

23927 

hold 

Preserve all messages that are read in the system mailbox instead of putting them 
in the mbox save file. The default shall be nohold. 

23928 

ignore 

Ignore interrupts while entering messages. The default shall be noignore. 

23929 

23930 

23931 

23932 

ignoreeof 

Ignore normal end-of-file during message input. Input can be terminated only by 
entering a period (' .') on a line by itself or by the command escape. The default 
shall be noignoreeof. See also dot above. 
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23933 

23934 

23935 

indentprefix 

-string 

A string that shall be added as a prefix to each line that is inserted into the message 
by the ~m command escape. This variable shall default to one <tab> character. 

23936 

23937 

keep 

When a system mailbox, secondary mailbox, or mb ox is empty, truncate it to zero 
length instead of removing it. The default shall be nokeep. 

23938 

23939 

23940 

keepsave 

Keep the messages that have been saved from the system mailbox into other files 
in the file designated by the variable MBOX, instead of deleting them. The default 
shall be nokeepsave. 

23941 

23942 

metoo 

Suppress the deletion of the login name of the user from the recipient list when 
replying to a message or sending to a group. The default shall be nometoo. 

23943 XSI 

23944 

23945 

23946 

23947 

onehop 

When responding to a message that was originally sent to several recipients, the 
other recipient addresses are normally forced to be relative to the originating 
author's machine for the response. This flag disables alteration of the recipients' 
addresses, improving efficiency in a network where all machines can send directly 
to all other machines (that is, one hop away). The default shall be noonehop. 

23948 

23949 

23950 

outfolder 

Cause the files used to record outgoing messages to be located in the directory 
specified by the folder variable unless the path name is absolute. The default shall 
be nooutfolder. See the record variable. 

23951 

23952 

page 

Insert a <form-feed> after each message sent through the pipe created by the pipe 
command. The default shall be nopage. 

23953 

23954 

23955 

prompt=sfraig 

Set the command-mode prompt to string. If string is null or if noprompt is set, no 
prompting shall occur. The default shall be to prompt with the string " ? ". 

23956 

23957 

quiet 

Refrain from writing the opening message and version when entering mailx. The 
default shall be noquiet. 

23958 

23959 

record=/z/e 

Record all outgoing mail in the file with the path name file. The default shall be 
norecord. See also outfolder above. 

23960 

23961 

save 

Enable saving of messages in the dead-letter file on interrupt or delivery error. See 
the variable DEAD for the location of the dead-letter file. The default shall be save. 

23962 

23963 

23964 

23965 

23966 

scteen=number 

Set the number of lines in a screenful of headers for the headers and z commands. 
If screen is not specified, a value based on the terminal type identified by the 
TERM environment variable, the window size, the baud rate, or some combination 
of these shall be used. 

23967 MAN 

sendwait 

Wait for the background mailer to finish before returning. The default shall be 

23968 


nosendwait. 

23969 

23970 

23971 

showto 

When the sender of the message was the user who is invoking mailx, write the 
information from the To: line instead of the From: line in the header summary. 
The default shall be noshowto. 

23972 

23973 

23974 

23975 

sign =string 

Set the variable inserted into the text of a message when the ~a command escape is 
given. The default shall be nosign. The character sequences ' \t' and ' \n' shall 
be recognized in the variable as <tab> and <newline> characters, respectively. (See 
also ~i in Command Escapes in mailx on page 637.) 

23976 

23977 

Sign -string 

Set the variable inserted into the text of a message when the "A command escape is 
given. The default shall be no Sign. The character sequences ' \t' and ' \n' shall 
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be recognized in the variable as <tab> and <newline> characters, respectively. 
toplines=number 

Set the number of lines of the message to write with the top command. The default 
shall be 5. 

Commands in mailx 

The following mailx commands shall be provided. In the following list, header refers to lines 
from the message header, as shown in the OUTPUT FILES section. Header-line refers to lines 
within the header that begin with one or more non-white-space characters, immediately 
followed by a colon and white space and continuing until the next line beginning with a non¬ 
white-space character or an empty line. Header-field refers to the portion of a header line prior 
to the first colon in that line. 

For each of the commands listed below, the command can be entered as the abbreviation (those 
characters in the Synopsis command word preceding the ' ['), the full command (all characters 
shown for the command word, omitting the ' [' and ' ] '), or any truncation of the full 
command down to the abbreviation. For example, the exit command (shown as ex[it] in the 
Synopsis) can be entered as ex, exi, or exit. 

The arguments to commands can be quoted, using the following methods: 

• An argument can be enclosed between paired double-quotes (" ") or single-quotes ("' ' 
any white space, shell word expansion, or backslash characters within the quotes shall be 
treated literally as part of the argument. A double-quote shall be treated literally within 
single-quotes and vice versa. These special properties of the quote marks shall occur only 
when they are paired at the beginning and end of the argument. 

• A backslash outside of the enclosing quotes shall be discarded and the following character 
treated literally as part of the argument. 

• An unquoted backslash at the end of a command line shall be discarded and the next line 
shall continue the command. 

File names, where expected, shall be subjected to the process of shell word expansions (see 
Section 2.6 on page 49); if more than a single path name results and the command is expecting 
one file, the effects are unspecified. If the file name begins with an unquoted plus sign, it shall 
not be expanded, but treated as the named file (less the leading plus) in the folder directory. (See 
the folder variable.) 

Declare Aliases 

Synopsis: a [lias] [alias [address...]] 

g[roup] [alias [address...]] 

Add the given addresses to the alias specified by alias. The names shall be substituted when 
alias is used as a recipient address specified by the user in an outgoing message (that is, other 
recipients addressed indirectly through the reply command shall not be substituted in this 
manner). Mail address alias substitution shall apply only when the alias string is used as a full 
address; for example, when hlj is an alias, hlj@posix.com does not trigger the alias substitution. If 
no arguments are given, write a listing of the current aliases to standard output. If only an alias 
argument is given, write a listing of the specified alias to standard output. These listings need 
not reflect the same order of addresses that were entered. 
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Declare Alternatives 

Synopsis: alt [ernates] name... 

(See also the metoo command.) Declare a list of alternative names for the user's login. When 
responding to a message, these names shall be removed from the list of recipients for the 
response. The comparison of names shall be in a case-insensitive manner. With no arguments, 
alternates shall write the current list of alternative names. 

Change Current Directory 

Synopsis: cd [ directory] 

chfdir] [ directory] 

Change directory. If directory is not specified, the contents of HOME shall be used. 

Copy Messages 

Synopsis: c[opy] [file] 

c[opy] [msglist] file 

man C[opy] [msglist] 

Copy messages to the file named by the path name file without marking the messages as saved. 
Otherwise, it shall be equivalent to the save command. 

man In the capitalized form, save the specified messages in a file whose name is derived from the 
author of the message to be saved, without marking the messages as saved. Otherwise, it shall 
be equivalent to the Save command. 

Delete Messages 

Synopsis: d[elete] [msglist] 

Mark messages for deletion from the mailbox. The deletions shall not occur until mailx quits (see 
the quit command) or changes mailboxes (see the folder command). If autoprint is set and there I 
are messages remaining after the delete command, the current message shall be written as I 
described for the print command (see the print command); otherwise, the mailx prompt shall be I 
written. 

Discard Header Fields 

Synopsis: di[scard] [header-field. . . ] 

igfnore] [header-field.. . ] 

Suppress the specified header fields when writing messages. Specified header-fields shall be 
added to the list of suppressed header fields. Examples of header fields to ignore are status and 
cc. The fields shall be included when the message is saved. The Print and Type commands shall 
override this command. The comparison of header fields shall be in a case-insensitive manner. If 
no arguments are specified, write a list of the currently suppressed header fields to standard 
output; the listing need not reflect the same order of header fields that were entered. 

If both retain and discard commands are given, discard commands shall be ignored. 
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Delete Messages and Display 

Synopsis: dp [msglist] 

dt [ msglist] 

Delete the specified messages as described for the delete command, except that the autoprint I 
variable shall have no effect, and the current message shall be written only if it was set to a I 
message after the last message deleted by the command. Otherwise, an informational message I 
to the effect that there are no further messages in the mailbox shall be written, followed by the I 
mailx prompt. I 

Echo a String 

Synopsis: ec[ho] string ... 

Echo the given strings, equivalent to the shell echo utility. 

Edit Messages 

Synopsis: e[dit] [ msglist] 

Edit the given messages. The messages shall be placed in a temporary file and the utility named 
by the EDITOR variable is invoked to edit each file in sequence. The default EDITOR is I 
unspecified. I 

The edit command does not modify the contents of those messages in the mailbox. 

Exit 

Synopsis: ex [it] 

x [it] 

Exit from mailx without changing the mailbox. No messages shall be saved in the mbox (see also 
quit). 

Change Folder 

Synopsis: fi[le] [file] 

fold[er] [file] 

Quit (see the quit command) from the current file of messages and read in the file named by the 
path name file. If no argument is given, the name and status of the current mailbox shall be 
written. 

Several unquoted special characters shall be recognized when used as file names, with the 
following substitutions: 

% The system mailbox for the invoking user. 

% user The system mailbox for user. 

# The previous file. 

& The current mbox. 

+ file The named file in the folder directory. (See the folder variable.) 

The default file shall be the current mailbox. 
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24092 Display List of Folders 

24093 Synopsis: folders 

24094 Write the names of the files in the directory set by the folder variable. The command specified by I 

24095 the LISTER environment variable shall be used (see the ENVIRONMENT VARIABLES section). I 

24096 Follow Up Specified Messages 

24097 Notes to Reviewers 

24098 This section zvith side shading zvill not appear in the final copy. - Ed. 


24099 Dl, XCU, ERN 300 raises an issue re this text. An action item is outstanding. 


24100 MAN 

Synopsis: 

fo[llowup] 

[message] 

24101 


F[ollowup] 

[ msglist ] 


24102 In the lowercase form, respond to a message, recording the response in a file whose name is 

24103 derived from the author of the message. Overrides the record variable, if set. See also the save 

24104 and copy commands and outfolder. 


24105 In the capitalized form, respond to the first message in the msglist, sending the message to the 

24106 author of each message in the msglist. The subject line shall be taken from the first message and 

24107 the response shall be recorded in a file whose name is derived from the author of the first 

24108 message. See also the Save and Copy commands and outfolder. 

24109 Display Header Summary for Specified Messages 

24110 Synopsis: f [rom] [msglist] 

24111 Write the header summary for the specified messages. 

24112 Display Header Summary 

24113 Synopsis: h[eaders] [message] 

24114 Write the page of headers that includes the message specified. If the message argument is not I 

24115 specified, the current message shall not change. However, if the message argument is specified, I 

24116 the current message shall become the message that appears at the top of the page of headers that I 

24117 includes the message specified. The screen variable sets the number of headers per page. See I 

24118 also the z command. 

24119 Help 

24120 Synopsis: hel [p] 

24121 ? 

24122 Write a summary of commands. 

24123 Hold Messages 

24124 Synopsis: ho [Id] [msglist] 

24125 pre [serve] [ msglist] 

24126 Mark the messages in msglist to be retained in the mailbox when mailx terminates. This shall 

24127 override any commands that might previously have marked the messages to be deleted. During 

24128 the current invocation of mailx, only the delete, dp, or dt commands shall remove the preserve 

24129 marking of a message. 
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Execute Commands Conditionally 

Synopsis: i [ f ] s|r 

mail-commands 
el[se] 

mail-commands 
en[dif] 

Execute commands conditionally, where if s executes the following mail-commands, up to an 
else or endif, if the program is in Send Mode, and if r shall cause the mail-commands to be 
executed only in Receive Mode. 

List Available Commands 

Synopsis: l[ist] 

Write a list of all commands available. No explanation shall be given. 

Mail a Message 

Synopsis: m[ail] address... 

Mail a message to the specified addresses or aliases. 

Direct Messages to mbox 

Synopsis: mb [ox] [ msglist ] 

Arrange for the given messages to end up in the mbox save file when mailx terminates normally. 
See MBOX. See also the exit and quit commands. 

Process Next Specified Message 

Synopsis: n[ext] [message] 

If the current message has not been written (for example, by the print command) since mailx I 
started or since any other message was the current message, behave as if the print command I 
was entered. Otherwise, if there is an undeleted message after the current message, make it the I 
current message and behave as if the print command was entered. Otherwise, an informational I 
message to the effect that there are no further messages in the mailbox shall be written, followed I 
by the mailx prompt. I 

Pipe Message 

Synopsis: pi[pe] [[msglist] command ] 

I [[ msglist ] command ] 

Pipe the messages through the given command by invoking the command interpreter specified 
by SHELL with two arguments: -c and command. (See also sh -c.) The application shall ensure I 
that the command is given as a single argument. Quoting, described previously, can be used to I 
accomplish this. If no arguments are given, the current message shall be piped through the I 
command specified by the value of the cmd variable. If the page variable is set, a <form-feed> I 
character shall be inserted after each message. 
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Display Message with Headers 

Synopsis: P[rint] [ msglist ] 

T[ype] [ msglist ] 

Write the specified messages, including all header lines, to standard output. Override 
suppression of lines by the discard, ignore, and retain commands. If crt is set, the messages 
longer than the number of lines specified by the crt variable shall be paged through the 
command specified by the PAGER environment variable. 

Display Message 

Synopsis: p[rint] [msglist] 

t[ype] [ msglist] 

Write the specified messages to standard output. If crt is set, the messages longer than the 
number of lines specified by the crt variable shall be paged through the command specified by 
the PAGER environment variable. 

Quit 

Synopsis: q[uit] 

end-of-file 

Terminate mailx, storing messages that were read in mbox (if the current mailbox is the system 
mailbox and unless hold is set), deleting messages that have been explicitly saved (unless 
keepsave is set), discarding messages that have been deleted, and saving all remaining messages 
in the mailbox. 

Reply to a Message List 

Synopsis: R[eply] [msglist] 

R[espond] [msglist] 

Mail a reply message to the sender of each message in the msglist. The subject line shall be 
formed by concatenating Re:<space> (unless it already begins with that string) and the subject 
from the first message. If record is set to a file name, the response shall be saved at the end of 
that file. 

See also the flipr variable. 

Reply to a Message 

Synopsis: r[eply] [message] 

r[espond] [message] 

Mail a reply message to all recipients included in the header of the message. The subject line 
shall be formed by concatenating Re:<space> (unless it already begins with that string) and the 
subject from the message. If record is set to a file name, the response shall be saved at the end of 
that file. 

See also the flipr variable. 
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Retain Header Fields 

Synopsis: ret [ain] [header-field. . . ] 

Retain the specified header fields when writing messages. This command shall override all 
discard and ignore commands. The comparison of header fields shall be in a case-insensitive 
manner. If no arguments are specified, write a list of the currently retained header fields to 
standard output; the listing need not reflect the same order of header fields that were entered. 

Save Messages 

Synopsis: s[ave] [file] 

s[ave] [msglist] file 
man S[ave] [msglist] 

Save the specified messages in the file named by the path name file, or the mbox if the file 
argument is omitted. The file shall be created if it does not exist; otherwise, the messages shall be 
appended to the file. The message shall be put in the state saved, and shall behave as specified in I 
the description of the saved state when the current mailbox is exited by the quit or file I 
command. I 

man In the capitalized form, save the specified messages in a file whose name is derived from the 
author of the first message. The name of the file shall be taken to be the author's name with all 
network addressing stripped off. See also the Copy, followup, and Followup commands and 
outfolder variable. 

Set Variables 

Synopsis: se[t] [name [= [string] ] ...] [name=numher ...] [no name ...] 

Define one or more variables called name. The variable can be given a null, string, or numeric 
value. Quoting and backslash escapes can occur anywhere in string, as described previously, as 
if the string portion of the argument were the entire argument. The forms name and name= shall 
be equivalent to name-"" for variables that take string values. The set command without 
arguments shall write a list of all defined variables and their values. The no name form shall be 
equivalent to unset name. 

Invoke a Shell 

Synopsis: sh[ell] 

Invoke an interactive command interpreter (see also SHELL). 

Display Message Size 

Synopsis: si[ze] [msglist] 

Write the size in bytes of each of the specified messages. 

Read mailx Commands From a File 

Synopsis: so[urce] file 

Read and execute commands from the file named by the path name file and return to command 
mode. 
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Display Beginning of Messages 

Synopsis: to[p] [ msglist ] 

Write the top few lines of each of the specified messages. If the toplines variable is set, it is taken 

as the number of lines to write. The default shall be 5. 

Touch Messages 

Synopsis: tou[ch] [msglist] 

Touch the specified messages. If any message in msglist is not specifically deleted nor saved in a 
file, it shall be placed in the mbox upon normal termination. See exit and quit. 

Delete Aliases 

Synopsis: una[lias] [alias] . . . 

Delete the specified alias names. If a specified alias does not exist, the results are unspecified. 

Undelete Messages 

Synopsis: u[ndelete] [msglist] I 

Change the state of the specified messages from deleted to read. If autoprint is set, the last I 
message of those restored shall be written. If msglist is not specified, the message shall be I 
selected as follows: I 

• If there are any deleted messages that follow the current message, the first of these shall be I 

chosen. I 

• Otherwise, the last deleted message that also precedes the current message shall be chosen. I 

Unset Variables I 

Synopsis: uns [et] name... 

Cause the specified variables to be erased. I 

Edit Message with Full-Screen Editor I 

Synopsis: v[isual] [msglist] I 

Edit the given messages with a screen editor. Each message shall be placed in a temporary file, I 
and the utility named by the VISUAL variable shall be invoked to edit each file in sequence. The I 
default editor shall be vi. I 

The visual command does not modify the contents of those messages in the mailbox. 

Write Messages to a File 

Synopsis: w[rite] [ msglist ] file 

Write the given messages to the file specified by the path name file, minus the message header. 
Otherwise, it shall be equivalent to the save command. 
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24284 

24285 

24286 

24287 

24288 

24289 

24290 

24291 

24292 

24293 

24294 

24295 

24296 

24297 

24298 

24299 

24300 

24301 

24302 

24303 

24304 

24305 

24306 

24307 

24308 


Scroll Header Display 

Synopsis: z [ + | —] 

Scroll the header display forward (if ' +' is specified or if no option is specified) or backward (if 
is specified) one screenful. The number of headers written shall be set by the screen 
variable. 

Invoke Shell Command 

Synopsis: ! command 

Invoke the command interpreter specified by SHELL with two arguments: -c and command. 
(See also sh -c.) If the bang variable is set, each unescaped occurrence of ' !' in command shall 
be replaced with the command executed by the previous ! command or ~! command escape. 

Null Command 

Synopsis: # comment 

This null command (comment) shall be ignored by mailx. 

Display Current Message Number 

Synopsis: 

Write the current message number. 

Command Escapes in mailx 

The following commands can be entered only from input mode, by beginning a line with the 
escape character (by default, tilde ('"'))• See the escape variable description for changing this 
special character. The format for the commands shall be: 

<ESC ><command-char><separator> [ <arguments >] 

where the <sepamtor> can be zero or more <blank> characters. 

In the following descriptions, the application shall ensure that the argument command (but not I 
mailx-command) is a shell command string. Any string acceptable to the command interpreter I 
specified by the SHELL variable when it is invoked as SHELL -c command_string shall be valid. 
The command can be presented as multiple arguments (that is, quoting is not required). 

Command escapes that are listed with msglist or mailx-command arguments are invalid in Send 
Mode and produce unspecified results. 

~! command Invoke the command interpreter specified by SHELL with two arguments: -c and 
command ; and then return to input mode. If the bang variable is set, each 
unescaped occurrence of ' !' in command shall be replaced with the command 
executed by the previous ! command or ~! command escape. 

Simulate end-of-file (terminate message input). 

mailx-command, mailx-command 

Perform the command-level request. 

~? Write a summary of command escapes. 

~A This shall be equivalent to ~i Sign. 

~a This shall be equivalent to ~i sign. 
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24309 

~b name... 

Add the names to the blind carbon copy (Bcc) list. 

24310 

~c name... 

Add the names to the carbon copy (Cc) list. 

24311 

~d 

Read in the dead-letter file. See DEAD for a description of this file. 

24312 

24313 

~e 

Invoke the editor, as specified by the EDITOR environment variable, on the partial 
message. 

24314 

24315 

24316 

24317 

~f [msglist] 

Forward the specified messages. The specified messages shall be inserted into the 
current message without alteration. This command escape also shall insert 
message headers into the message with field selection affected by the discard, 
ignore, and retain commands. 

24318 

24319 

24320 

~F [ msglist ] 

This shall be the equivalent of the ~f command escape, except that all headers shall 
be included in the message, regardless of previous discard, ignore, and retain 
commands. 

24321 

24322 

24323 

24324 

~h 

If standard input is a terminal, prompt for a Subject line and the To, Cc, and Bcc 
lists. Other implementation-dependent headers may also be presented for editing. 
If the field is written with an initial value, it can be edited as if it had just been 
typed. 

24325 

24326 

~i string 

Insert the value of the named variable, followed by a <newline> character, into the 
text of the message. If the string is unset or null, the message shall not be changed. 

24327 

24328 

24329 

24330 

"in [msglist] 

Insert the specified messages into the message, prefixing non-empty lines with the 
string in the indentprefix variable. This command escape also shall insert message 
headers into the message, with field selection affected by the discard, ignore, and 
retain commands. 

24331 

24332 

24333 

~M [msglist] This shall be the equivalent of the ~m command escape, except that all headers 
shall be included in the message, regardless of previous discard, ignore, and retain 
commands. 

24334 

24335 

24336 

~P 

Write the message being entered. If the message is longer than crt lines (see 
Internal Variables in mailx on page 626), the output shall be paginated as 
described for the PAGER variable. 

24337 

24338 

24339 

~q 

Quit (see the quit command) from input mode by simulating an interrupt. If the 
body of the message is not empty, the partial message shall be saved in the dead- 
letter file. See DEAD for a description of this file. 

24340 

24341 

24342 

24343 

24344 

24345 

"~r file, ~< file, ~r ! command, ~< ! command” 

Read in the file specified by the path name file. If the argument begins with an 
exclamation-mark (' !'), the rest of the string shall be taken as an arbitrary system 
command; the command interpreter specified by SHELL shall be invoked with two 
arguments: -c and command. The standard output of command shall be inserted 
into the message. 

24346 

~s string 

Set the subject line to string. 

24347 

~t name... 

Add the given names to the To list. 

24348 

24349 

~v 

Invoke the full-screen editor, as specified by the VISUAL environment variable, on 
the partial message. 

24350 

24351 

24352 

~w file 

Write the partial message, without the header, onto the file named by the path 
name file. The file shall be created or the message shall be appended to it if the file 
exists. 
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24353 ~x 


Exit as with ~q, except the message shall not be saved in the dead-letter file. 


24354 

24355 

24356 

24357 

24358 

24359 


~ I command Pipe the body of the message through the given command by invoking the 
command interpreter specified by SHELL with two arguments: -c and command. 
If the command returns a successful exit status, the standard output of the 
command shall replace the message. Otherwise, the message shall remain 
unchanged. If the command fails, an error message giving the exit status shall be 
written. 


24360 EXIT STATUS 

24361 When the -e option is specified, the following exit values are returned: 

24362 0 Mail was found. 

24363 >0 Mail was not found or an error occurred. 

24364 Otherwise, the following exit values are returned: 

24365 0 Successful completion; note that this status implies that all messages were sent, but it gives 

24366 no assurances that any of them were actually delivered. 

24367 >0 An error occurred. 


24368 CONSEQUENCES OF ERRORS 

24369 When in input mode (Receive Mode) or Send Mode: 

24370 • If an error is encountered processing a command escape (see Command Escapes in mailx on 

24371 P a g e 637), a diagnostic message shall be written to standard error, and the message being 

24372 composed may be modified, but this condition shall not prevent the message from being 

24373 sent. 

24374 • Other errors shall prevent the sending of the message. 

24375 When in command mode: 

24376 • Default. 

24377 APPLICATION USAGE 

24378 Delivery of messages to remote systems requires the existence of communication paths to such 

24379 systems. These need not exist. 

24380 Input lines are limited to |LINE_MAX} bytes, but mailers between systems may impose more 

24381 severe line-length restrictions. This volume of IEEE Std. 1003.1-200x does not place any 

24382 restrictions on the length of messages handled by mailx, and for delivery of local messages the 

24383 only limitations should be the normal problems of available disk space for the target mail file. 

24384 When sending messages to external machines, applications are advised to limit messages to less 

24385 than 100 kilobytes because some mail gateways impose message-length restrictions. 

24386 The format of the system mailbox is intentionally unspecified. Not all systems implement 

24387 system mailboxes as flat files, particularly with the advent of multimedia mail messages. Some 

24388 system mailboxes may be multiple files, others records in a database. The internal format of the 

24389 messages themselves are specified with the historical format from Version 7, but only after they 

24390 have been saved in some file other than the system mailbox. This was done so that many 

24391 historical applications expecting text-file mailboxes are not broken. 

24392 Some new formats for messages can be expected in the future, probably including binary data, 

24393 bit maps, and various multimedia objects. As described here, mailx is not prohibited from 

24394 handling such messages, but it must store them as text files in secondary mailboxes (unless 

24395 some extension, such as a variable or command line option, is used to change the stored format). 

24396 Its method of doing so is implementation-dependent and might include translating the data into 
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24397 

24398 

24399 

24400 

24401 

24402 

24403 

24404 

24405 

24406 

24407 

24408 

24409 

24410 

24411 

24412 

24413 

24414 

24415 

24416 

24417 

24418 

24419 

24420 

24421 

24422 

24423 

24424 

24425 

24426 

24427 

24428 

24429 

24430 

24431 

24432 

24433 

24434 

24435 

24436 

24437 

24438 

24439 

24440 

24441 


text file-compatible or readable form or omitting certain portions of the message from the stored 
output. 

The discard and ignore commands are not inverses of the retain command. The retain 
command discards all header-fields except those explicitly retained. The discard command 
keeps all header-fields except those explicitly discarded. If headers exist on the retained header 
list, discard and ignore commands are ignored. 

EXAMPLES 

None. 

RATIONALE 

The standard developers felt strongly that a method for applications to send messages to 
specific users was necessary. The obvious example is a batch utility, running non-interactively, 
that wishes to communicate errors or results to a user. However, the actual format, delivery 
mechanism, and method of reading the message are clearly beyond the scope of this volume of 
IEEE Std. 1003.1-200x. 

The intent of this command is to provide a simple, portable interface for sending messages non- 
interactively. It merely defines a "front-end” to the historical mail system. It is suggested that 
implementations explicitly denote the sender and recipient in the body of the delivered message. 
Further specification of formats for either the message envelope or the message itself were 
deliberately not made, as the industry is in the midst of changing from the current standards to a 
more internationalized standard and it is probably incorrect, at this time, to require either one. 

Implementations are encouraged to conform to the various delivery mechanisms described in 
the CCITT X.400 standards or to the equivalent Internet standards, described in Internet Request 
for Comment (RFC) documents RFC 819, RFC 822, RFC 920, RFC 921, and RFC 1123. 

Many historical systems modified each body line that started with From by prefixing the ' F' 
with ' . It is unnecessary, but allowed, to do that when the string does not follow a blank line 

because it cannot be confused with the next header. 

XSI-conformant systems support the following internal variable: 

debug Enable verbose diagnostics for debugging. Messages shall not be delivered. The 

default shall be no debug. 

The edit and visual commands merely edit the specified messages in a temporary file. They do 
not modify the contents of those messages in the mailbox; such a capability could be added as an 
extension, such as by using different command names. 

The restriction on a subject line being |LINE_MAX}-10 bytes is based on the historical format 
that consumes 10 bytes for Subject: and the trailing <newline>. Many historical mailers that a 
message may encounter on other systems are not able to handle lines that long, however. 

Like the utilities logger and Ip, mailx admittedly is difficult to test. This was not deemed sufficient 
justification to exclude this utility from this volume of IEEE Std. 1003.1-200x. It is also arguable 
that it is, in fact, testable, but that the tests themselves are not portable. 

When mailx is being used by an application that wishes to receive the results as if none of the 
User Portability Utilities option features were supported, the DEAD environment variable must 
be set to /dev/null. Otherwise, it may be subject to the file creations described in mailx 
ASYNCHRONOUS EVENTS. Similarly, if the MAILRC environment variable is not set to 
/dev/null, historical versions of mailx and Mail read initialization commands from a file before 
processing begins. Since the initialization that a user specifies could alter the contents of 
messages an application is trying to send, such applications must set MAILRC to /dev/null. 
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24442 

24443 

24444 

24445 

24446 

24447 

24448 

24449 

24450 

24451 

24452 

24453 

24454 

24455 

24456 

24457 

24458 

24459 

24460 

24461 

24462 

24463 

24464 

24465 

24466 

24467 

24468 

24469 

24470 

24471 

24472 

24473 

24474 

24475 

24476 

24477 

24478 

24479 

24480 

24481 

24482 

24483 

24484 

24485 

24486 


The description of LC_TIME uses "may affect" because many historical implementations do not 
or cannot manipulate the date and time strings in the incoming mail headers. Some headers 
found in incoming mail do not have enough information to determine the timezone in which the 
mail originated, and, therefore, mailx cannot convert the date and time strings into the internal 
form that then is parsed by routines like strftime( ) that can take LC_TIME settings into account. 
Changing all these times to a user-specified format is allowed, but not required. 

The paginator selected when PAGER is null or unset is partially unspecified to allow the System 
V historical practice of using pg as the default. Bypassing the pagination function, such as by 
declaring that cat is the paginator, would not meet with the intended meaning of this 
description. However, any "portable user" would have to set PAGER explicitly to get his or her 
preferred paginator on all systems. The paginator choice was made partially unspecified, unlike 
the VISUAL editor choice (mandated to be vi) because most historical pagers follow a common 
theme of user input, whereas editors differ dramatically. 

Options to specify addresses as cc (carbon copy) or bcc (blind carbon copy) were considered to 
be format details and were omitted. 

A zero exit status implies that all messages were sent, but it gives no assurances that any of them 
were actually delivered. The reliability of the delivery mechanism is unspecified and is an 
appropriate marketing distinction between systems. 

In order to conform to the Utility Syntax Guidelines, a solution was required to the optional file 
option-argument to -f. By making file an operand, the guidelines are satisfied and users remain 
portable. However, it does force implementations to support usage such as: 

mailx —fin mymail.box 

The no name method of unsetting variables is not present in all historical systems, but it is in 
System V and provides a logical set of commands corresponding to the format of the display of 
options from the mailx set command without arguments. 

The ask and asksub variables are the names selected by BSD and System V, respectively, for the 
same feature. They are synonyms in this volume of IEEE Std. 1003.1-200x. 

The mailx echo command was not documented in the BSD version and has been omitted here 
because it is not obviously useful for interactive users. 

The default prompt on the System V mailx is a question mark, on BSD Mail an ampersand. Since 
this volume of IEEE Std. 1003.1-200x chose the mailx name, it kept the System V default, 
assuming that BSD users would not have difficulty with this minor incompatibility (that they 
can override). 

The meanings of r and R are reversed between System V mailx and SunOS Mail. Once again, 
since this volume of IEEE Std. 1003.1-200x chose the mailx name, it kept the System V default, 
but allows the SunOS user to achieve the desired results using flipr, an internal variable in 
System V mailx, although it has not been documented in the SVID 

The indentprefix variable, the retain and unalias commands, and the ~F and ~M command 
escapes were adopted from 4.3 BSD Mail. 

The version command was not included because no sufficiently general specification of the 
version information could be devised that would still be useful to a portable user. This 
command name should be used by suppliers who wish to provide version information about the 
mailx command. 

The "implementation-specific (unspecified) system start-up file" historically has been named I 
/etc/mailx.rc, but this specific name and location are not required. I 
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24487 The intent of the wording for the next command is that if any command has already displayed I 

24488 the current message it should display a following message, but, otherwise, it should display the I 

24489 current message. Consider the command sequence: I 

24490 next 3 I 

24491 delete 3 I 

24492 next I 

24493 where the autoprint option was not set. The normative text specifies that the second next I 

24494 command should display a message following the third message, because even though the I 

24495 current message has not been displayed since it was set by the delete command, it has been I 

24496 displayed since the current message was anything other than message number 3. This does not I 

24497 always match historical practice in some implementations, where the command file address I 

24498 followed by next (or the default command) would skip the message for which the user had I 

24499 searched. I 

24500 FUTURE DIRECTIONS 

24501 None. I 

24502 SEE ALSO 

24503 ed, Is, more, vi 

24504 CHANGE HISTORY 

24505 First released in Issue 2. 

24506 Issue 4 

24507 Aligned with the ISO/IEC 9945-2:1993 standard. 

24508 This utility is now mandatory; it is optional in Issue 3. 

24509 Issue 5 

24510 The description of the EDITOR environment variable is changed to indicate that ed is the default 

24511 editor if this variable is not set. In previous issues, this default was not stated explicitly at this 

24512 point but was implied further down in the text. 

24513 FUTURE DIRECTIONS section added. 

24514 Issue 6 

24515 The following new requirements on POSIX implementations derive from alignment with the 

24516 Single UNIX Specification: 

24517 • The -F option is added. 

24518 • The allnet, debug, and sendwait internal variables are added. 

24519 • The C, ec, to, F, and S mailx commands are added. 

24520 In the DESCRIPTION and ENVIRONMENT VARIABLES sections, text stating " HOME 

24521 directory" is replaced by "directory referred to by the HOME environment variable". I 

24522 The mailx utility is aligned with the IEEE P1003.2b draft standard, which included various I 

24523 clarifications to resolve PASC Interpretations submitted for the ISO POSIX-2:1993 standard. In I 

24524 particular, the changes here address PASC Interpretations 1003.2-92 #10, 11, 103, 106, 108, 114, I 

24525 115, 122, and 129. I 

24526 The normative text is reworded to avoid use of the term "must" for application requirements. I 
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24527 NAME 

24528 make — maintain, update, and regenerate groups of programs (DEVELOPMENT) 

24529 SYNOPSIS 

24530 SD make [— einpqrst] [—f makefile ] . . . [ —k | — S] [ macro=value ] . . . 

24531 [target_name . . . ] 

24532 


24533 DESCRIPTION 

24534 The make utility can be used as a part of software development to update files that are derived 

24535 from other files. A typical case is one where object files are derived from the corresponding 

24536 source files. The make utility examines time relationships and updates those derived files (called 

24537 targets) that have modified times earlier than the modified times of the files (called 

24538 prerequisites) from which they are derived. A description file (makefile) contains a description 

24539 of the relationships between files, and the commands that the application shall execute to I 

24540 update the targets to reflect changes in their prerequisites. Each specification, or rule, shall I 

24541 consist of a target, optional prerequisites, and optional commands to be executed when a I 

24542 prerequisite is newer than the target. There are two types of rule: I 

24543 1. Inference rules, which have one target name with at least one period (' .') and no slash 

24544 ('/') 

24545 2. Target rules, which can have more than one target name 

24546 In addition, make shall have a collection of built-in macros and inference rules that infer 

24547 prerequisite relationships to simplify maintenance of programs. 

24548 To receive exactly the behavior described in this section, the user shall ensure that a portable I 

24549 makefile: I 

24550 • Includes the special target .POSIX I 

24551 • Omits any special target reserved for implementations (a leading period followed by I 

24552 uppercase letters) that has not been specified by this section 

24553 The behavior of make is unspecified if either or both of these conditions are not met. 


24554 OPTIONS 

24555 The make utility shall conform to the System Interface Definitions volume of I 

24556 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

24557 The following options shall be supported: 


24558 -e Cause environment variables, including those with null values, to override macro 

24559 assignments within makefiles. 


24560 

24561 

24562 

24563 

24564 


-f makefile Specify a different makefile. The argument makefile is a path name of a description 
file, which is also referred to as the makefile. A path name of shall denote the 
standard input. There can be multiple instances of this option, and they shall be 
processed in the order specified. The effect of specifying the same option- 
argument more than once is unspecified. 


24565 -i Ignore error codes returned by invoked commands. This mode is the same as if the 

24566 special target .IGNORE were specified without prerequisites. 


24567 -k Continue to update other targets that do not depend on the current target if a non- 

24568 ignored error occurs while executing the commands to bring a target up-to-date. 


24569 -n Write commands that would be executed on standard output, but do not execute 

24570 them. However, lines with a plus sign (' +') prefix shall be executed. In this mode. 
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lines with an at sign (' @') character prefix shall be written to standard output. 

-p Write to standard output the complete set of macro definitions and target 

descriptions. The output format is unspecified. 

-q Return a zero exit value if the target file is up-to-date; otherwise, return an exit 

value of 1. Targets shall not be updated if this option is specified. However, a I 
makefile command line (associated with the targets) with a plus sign (' +') prefix I 
shall be executed. 

-r Clear the suffix list and does not use the built-in rules. 

-S Terminate make if an error occurs while executing the commands to bring a target 

up-to-date. This shall be the default and the opposite of -k. 

-s Do not write makefile command lines or touch messages (see -t) to standard I 

output before executing. This mode shall be the same as if the special target 
.SILENT were specified without prerequisites. 

-t Update the modification time of each target as though a touch target had been I 

executed. Targets that have prerequisites but no commands (see Target Rules on I 
page 647), or that are already up-to-date, shall not be touched in this manner. 
Write messages to standard output for each target file indicating the name of the I 

file and that it was touched. Normally, the makefile command lines associated I 

with each target are not executed. However, a command line with a plus sign I 
(' +') prefix shall be executed. 

Any options specified in the MAKEFLAGS environment variable shall be evaluated before any I 
options specified on the make utility command line. If the -k and -S options are both specified I 
on the make utility command line or by the MAKEFLAGS environment variable, the last option I 
specified shall take precedence. If the -f or -p options appear in the MAKEFLAGS environment I 
variable, the result is undefined. I 


24596 OPERANDS 


24604 STDIN 


The following operands shall be supported: 

target_name Target names, as defined in the EXTENDED DESCRIPTION section. If no target is 
specified, while make is processing the makefiles, the first target that make 
encounters that is not a special target or an inference rule shall be used. 

macro=value Macro definitions, as defined in Macros on page 649. 

If the target_name and macro-value operands are intermixed on the make utility command line, I 
the results are unspecified. I 

The standard input shall be used only if the makefile option-argument is . See the INPUT 
FILES section. 


24607 INPUT FILES 

24608 The input file, otherwise known as the makefile, is a text file containing rules, macro definitions, 

24609 and comments. 

24610 ENVIRONMENT VARIABLES 

24611 The following environment variables shall affect the execution of make : 

24612 LANG Provide a default value for the internationalization variables that are unset or null. 

24613 If LANG is unset or null, the corresponding value from the implementation- 

24614 dependent default locale shall be used. If any of the internationalization variables 

24615 contains an invalid setting, the utility shall behave as if none of the variables had 
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24616 

24617 

24618 

24619 

24620 

24621 

24622 

24623 

24624 

24625 

24626 

24627 

24628 

24629 

24630 

24631 

24632 

24633 

24634 

24635 

24636 

24637 

24638 

24639 

24640 

24641 

24642 

24643 

24644 

24645 

24646 

24647 

24648 

24649 

24650 

24651 

24652 

24653 

24654 

24655 

24656 

24657 

24658 

24659 


been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

MAKEFLAGS 

This variable shall be interpreted as a character string representing a series of 
option characters to be used as the default options. The implementation shall 
accept both of the following formats (but need not accept them when intermixed): 

• The characters are option letters without the leading hyphens or <blank> 
character separation used on a make utility command line. 

• The characters are formatted in a manner similar to a portion of the make utility 
command line: options are preceded by hyphens and <blank> character- 
separated as described in the System Interface Definitions volume of 
IEEEStd. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. The macro-value 
macro definition operands can also be included. The difference between the 
contents of MAKEFLAGS and the make utility command line is that the contents 
of the variable shall not be subjected to the word expansions (see Section 2.6 on 
page 49) associated with parsing the command line values. 

The value of the SHELL environment variable shall not be used as a macro and 
shall not be modified by defining the SHELL macro in a makefile or on the make 
utility command line. All other environment variables, including those with null 
values, shall be used as macros. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
xsi PROJECTDIR 

Provide a directory to be used to search for SCCS files not found in the current 
directory. In all of the following cases, the search for SCCS files is made in the 
directory SCCS in the identified directory. If the value of PROJECTDIR begins 
with a slash, it shall be considered an absolute path name; otherwise, the value of 
PROJECTDIR is treated as a user name and that user's initial working directory 
shall be examined for a subdirectory src or source. If such a directory is found, it 
shall be used. Otherwise, the value is used as a relative path name. 

If PROJECTDIR is not set or has a null value, the search for SCCS files shall be 
made in the directory SCCS in the current directory. 

The setting of PROJECTDIR affects all files listed in the remainder of this utility 
description for files with a component named SCCS. 

The value of the SHELL environment variable shall not be used as a macro and shall not be 
modified by defining the SHELL macro in a makefile or on the command line. All other 
environment variables, including those with null values, shall be used as macros, as defined in 
Macros on page 649. 
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24660 ASYNCHRONOUS EVENTS 

24661 If not already ignored, make shall trap SIGHUP, SIGTERM, SIGINT, and SIGQUIT and remove 

24662 the current target unless the target is a directory or the target is a prerequisite of the special 

24663 target .PRECIOUS or unless one of the -n, -p, or -q options was specified. Any targets removed 

24664 in this manner shall be reported in diagnostic messages of unspecified format, written to 

24665 standard error. After this cleanup process, if any, make shall take the standard action for all other 

24666 signals. 

24667 STDOUT 

24668 The make utility shall write all commands to be executed to standard output unless the -s option 

24669 was specified, the command is prefixed with an at sign, or the special target .SILENT has either 

24670 the current target as a prerequisite or has no prerequisites. If make is invoked without any work 

24671 needing to be done, it shall write a message to standard output indicating that no action was I 

24672 taken. If the -t option is present and a file is touched, make shall write to standard output a I 

24673 message of unspecified format indicating that the file was touched, including the file name of I 

24674 the file. I 

24675 STDERR 

24676 Used only for diagnostic messages. 

24677 OUTPUT FILES 

24678 Files can be created when the -t option is present. Additional files can also be created by the I 

24679 utilities invoked by make. I 

24680 EXTENDED DESCRIPTION 

24681 The make utility attempts to perform the actions required to ensure that the specified targets are 

24682 up-to-date. A target is considered out-of-date if it is older than any of its prerequisites or if it 

24683 does not exist. The make utility shall treat all prerequisites as targets themselves and recursively 

24684 ensure that they are up-to-date, processing them in the order in which they appear in the rule. 

24685 The make utility shall use the modification times of files to determine whether the corresponding 

24686 targets are out-of-date. 

24687 After make has ensured that all of the prerequisites of a target are up-to-date and if the target is 

24688 out-of-date, the commands associated with the target entry shall be executed. If there are no 

24689 commands listed for the target, the target shall be treated as up-to-date. 

24690 Makefile Syntax 

24691 A makefile can contain rules, macro definitions (see Macros on page 649), and comments. There 

24692 are two kinds of rules: inference rules and target rules. The make utility shall contain a set of 

24693 built-in inference rules. If the -r option is present, the built-in rules shall not be used and the 

24694 suffix list shall be cleared. Additional rules of both types can be specified in a makefile. If a rule I 

24695 is defined more than once, the value of the rule shall be that of the last one specified. Macros can I 

24696 also be defined more than once, and the value of the macro is specified in Macros on page 649. I 

24697 Comments start with a number sign (' #') and continue until an unescaped <newline> character I 

24698 is reached. 

24699 xsi By default, the following files shall be tried in sequence: ./makefile, ./Makefile, ./s.makefile, 

24700 SCCS/s.makefile, ./s.Makefile, and SCCS/s.Makefile. 

24701 The -f option shall direct make to ignore any of these default files and use the specified argument 

24702 as a makefile instead. If the ' —' argument is specified, standard input shall be used. 

24703 The term makefile is used to refer to any rules provided by the user, whether in ./makefile or its 

24704 variants, or specified by the -f option. 
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The rules in makefiles shall consist of the following types of lines: target rules, including special 
targets (see Target Rules), inference rules (see Inference Rules on page 650), macro definitions 
(see Macros on page 649), empty lines, and comments. Comments start with a number sign 
(' #') and continue until an unescaped <newline> character is reached. 

When an escaped <newline> (one preceded by a backslash) is found anywhere in the makefile I 
except in a command line, it shall be replaced, along with any leading white space on the I 
following line, with a single <space>. When an escaped <newline> is found in a command line I 
in a makefile, the command line shall contain the backslash, the <newline>, and the next line, I 
except that the first character of the next line shall not be included if it is a <tab>. I 

Makefile Execution 

Makefile command lines shall be processed one at a time by writing the makefile command line I 
to the standard output (unless one of the conditions listed under ' @' suppresses the writing) I 
and executing the command(s) in the line. A <tab> character may precede the command to I 
standard output. Command execution shall be as if the makefile command line were the I 
argument to the system() function. The environment for the command being executed shall I 
contain all of the variables in the environment of make. I 

By default, when make receives a non-zero status from the execution of a command, it terminates 
with an error message to standard error. 

Makefile command lines can have one or more of the following prefixes: a hyphen ('-'), an at I 
sign (' @'), or a plus sign ('+')• These modify the way in which make processes the command. 
When a command is written to standard output, the prefix shall not be included in the output. 

- If the command prefix contains a hyphen, or the -i option is present, or the special target 
.IGNORE has either the current target as a prerequisite or has no prerequisites, any error 
found while executing the command shall be ignored. 

@ If the command prefix contains an at sign and the make utility command line -n option is I 
not specified, or the -s option is present, or the special target .SILENT has either the current 
target as a prerequisite or has no prerequisites, the command shall not be written to 
standard output before it is executed. 

+ If the command prefix contains a plus sign, this indicates a makefile command line that I 
shall be executed even if -n, -q, or -t is specified. I 

Target Rules 

Target rules are formatted as follows: 

target [target...]: [prerequisite ...][; command] 

[<tab> command 
<tab >command 

. . .] 

line that does not begin with <tab> 

Target entries are specified by a <blank> character-separated, non-null list of targets, then a 
colon, then a <blank> character-separated, possibly empty list of prerequisites. Text following a 
semicolon, if any, and all following lines that begin with a <tab> character, are makefile I 
command lines to be executed to update the target. The first non-empty line that does not begin I 
with a <tab> character or ' #' shall begin a new entry. An empty or blank line, or a line I 
beginning with ' #', may begin a new entry. 
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Applications shall select target names from the set of characters consisting solely of periods, 
underscores, digits, and alphabetics from the portable character set (see the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). 
Implementations may allow other characters in target names as extensions. The interpretation of 
targets containing the characters ' %' and ' ' is implementation-dependent. 

A target that has prerequisites, but does not have any commands, can be used to add to the 
prerequisite list for that target. Only one target rule for any given target can contain commands. 

Lines that begin with one of the following are called special targets and control the operation of 
make: 


24757 

24758 

24759 


.DEFAULT If the makefile uses this special target, the application shall ensure that it is I 
specified with commands, but without prerequisites. The commands shall be used I 
by make if there are no other rules available to build a target. I 
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.IGNORE Prerequisites of this special target are targets themselves; this shall cause errors 
from commands associated with them to be ignored in the same manner as 
specified by the -i option. Subsequent occurrences of .IGNORE shall add to the 
list of targets ignoring command errors. If no prerequisites are specified, make shall 
behave as if the -i option had been specified and errors from all commands 
associated with all targets shall be ignored. 


24766 

24767 

24768 

24769 


•POSIX The application shall ensure that this special target is specified without I 
prerequisites or commands. If it appears before the first non-comment line in the I 
makefile, make shall process the makefile as specified by this section; otherwise, the I 
behavior of make is unspecified. 
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.PRECIOUS Prerequisites of this special target shall not be removed if make receives one of the 
asynchronous events explicitly described in the ASYNCHRONOUS EVENTS 
section. Subsequent occurrences of .PRECIOUS shall add to the list of precious 
files. If no prerequisites are specified, all targets in the makefile shall be treated as 
if specified with .PRECIOUS. 
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•SCCS_GET The application shall ensure that this special target is specified without I 
prerequisites. If this special target is included in a makefile, the commands I 
specified with this target shall replace the default commands associated with this I 
special target (see Default Rules on page 653). The commands specified with this I 
target are used to get all SCCS files that are not found in the current directory. 

When source files are named in a dependency list, make treats them just like any 
other target. Because the source file is presumed to be present in the directory, 
there is no need to add an entry for it to the makefile. When a target has no 
dependencies, but is present in the directory, make assumes that that file is up-to- 
date. If, however, an SCCS file named SCCSIs.source_file is found for a target 
source_file, make does some additional checking to assure that the target is up-to- 
date. If the target is missing, or if the SCCS file is newer, make automatically issues 
the commands specified for the .SCCS_GET special target to retrieve the most 
recent version. However, if the target is writable by anyone, make does not retrieve 
a new version. 
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•SILENT Prerequisites of this special target are targets themselves; this shall cause 
commands associated with them to not be written to the standard output before 
they are executed. Subsequent occurrences of .SILENT shall add to the list of 
targets with silent commands. If no prerequisites are specified, make shall behave 
as if the -s option had been specified and no commands or touch messages 
associated with any target shall be written to standard output. 
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.SUFFIXES Prerequisites of .SUFFIXES shall be appended to the list of known suffixes and are 
used in conjunction with the inference rules (see Inference Rules on page 650). If 
.SUFFIXES does not have any prerequisites, the list of known suffixes shall be I 
cleared. I 

The special targets .IGNORE, .POSIX, .PRECIOUS, .SILENT, and .SUFFIXES shall be specified I 
without commands. I 

Targets with names consisting of a leading period followed by the uppercase letters "POSIX" I 
and then any other characters are reserved for future standardization. Targets with names 
consisting of a leading period followed by one or more uppercase letters are reserved for 
implementation extensions. 

Macros 

Macro definitions are in the form: 

stringl = [ string2 ] 

The macro named stringl is defined as having the value of string2, where string2 is defined as all 
characters, if any, after the equal sign, up to a comment character (' #') or an unescaped 
<newline> character. Any <blank> characters immediately before or after the equal sign shall be 
ignored. 

Applications shall select macro names from the set of characters consisting solely of periods, I 
underscores, digits, and alphabetics from the portable character set (see the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). A macro name I 
shall not contain an equals sign. Implementations may allow other characters in macro names I 
as extensions. I 

Macros can appear anywhere in the makefile. $(stringl) or ${stringlj shall be replaced by I 
string2, as follows: I 

• Macros in target lines shall be evaluated when the target line is read. I 

• Macros in makefile command lines shall be evaluated when the command is executed. I 

• Macros in the string before the equals sign in a macro definition shall be evaluated when the I 

macro assignment is made. I 

• Macros after the equals sign in a macro definition shall not be evaluated until the defined I 

macro is used in a rule or command, or before the equals sign in a macro definition. I 

The parentheses or braces are optional if stringl is a single character. The macro $$ shall be I 
replaced by the single character ' $'. 

The forms $(s tringl[:snbstl=[subst2]]) or ${stringl[:snbstl=[subst2]]} can be used to replace all I 
occurrences of snbstl with snbst2 when the macro substitution is performed. The snbstl to be 
replaced shall be recognized when it is a suffix at the end of a word in stringl (where a word., in 
this context, is defined to be a string delimited by the beginning of the line, a <blank> or 
<newline> character). 

Macro definitions shall be taken from the following sources, in the following logical order, I 
before the makefile(s) are read. I 

1. Macros specified on the make utility command line, in the order specified on the command I 
line. It is unspecified whether the internal macros defined in Internal Macros on page 652 I 
are accepted from this source. I 
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2. Macros defined by the MAKEFLAGS environment variable, in the order specified in the I 

environment variable. It is unspecified whether the internal macros defined in Internal I 
Macros on page 652 are accepted from this source. I 

3. The contents of the environment, excluding the MAKEFLAGS and SHELL variables and I 

including the variables with null values. I 

4. Macros defined in the inference rules built into make. I 

Macro definitions from these sources shall not override macro definitions from a lower- I 
numbered source. Macro definitions from a single source (for example, the make utility I 
command line, the MAKEFLAGS environment variable, or the other environment variables) shall I 
override previous macro definitions from the same source. I 

Macros defined in the makefile(s) shall override macro definitions that occur before them in the I 
makefile(s) and macro definitions from source 4. If the -e option is not specified, macros defined I 
in the makefile(s) shall override macro definitions from source 3. Macros defined in the I 
makefile(s) shall not override macro definitions from source 1. or source 2. I 

Before the makefile(s) are read, all of the make utility command line options (except -f and -p) I 
and make utility command line macro definitions (except any for the MAKEFLAGS macro), not I 
already included in the MAKEFLAGS macro, shall be added to the MAKEFLAGS macro. Other I 
implementation-dependent options and macros may also be added to the MAKEFLAGS macro. I 
If this modifies the value of the MAKEFLAGS macro, or, if the MAKEFLAGS macro is modified I 
at any subsequent time, the MAKEFLAGS environment variable shall be modified to match the I 
new value of the MAKEFLAGS macro. I 

Before the makefile(s) are read, all of the make utility command line macro definitions (except the I 
MAKEFLAGS macro or the SHELL macro) shall be added to the environment of make. Other I 
implementation-dependent variables may also be added to the environment of make. I 

The SHELL macro shall be treated specially. It shall be provided by make and set to the path I 
name of the shell command language interpreter (see sh on page 888). The SHELL environment 
variable shall not affect the value of the SHELL macro. If SHELL is defined in the makefile or is 
specified on the command line, it shall replace the original value of the SHELL macro, but shall 
not affect the SHELL environment variable. Other effects of defining SHELL in the makefile or 
on the command line are implementation-dependent. 

Inference Rules 

Inference rules are formatted as follows: 

target: 

<tab >command 
[<tab> command] 


line that does not begin with <tab> or # 

The application shall ensure that the target portion is a valid target name (see Target Rules on I 
page 647) of the form .s2 or .sl.s2 (where .si and .s2 are suffixes that have been given as 
prerequisites of the .SULLIXES special target and si and s2 do not contain any slashes or 
periods.) If there is only one period in the target, it is a single-suffix inference rule. Targets with 
two periods are double-suffix inference rules. Inference rules can have only one target before the 
colon. 

The application shall ensure that the makefile does not specify prerequisites for inference rules; I 
no characters other than white space shall follow the colon in the first line, except when creating I 
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the empty rule, described below. Prerequisites are inferred, as described below. I 

Inference rules can be redefined. A target that matches an existing inference rule shall overwrite 
the old inference rule. An empty rule can be created with a command consisting of simply a 
semicolon (that is, the rule still exists and is found during inference rule search, but since it is 
empty, execution has no effect). The empty rule also can be formatted as follows: 

rule: ; 

where zero or more <blank> characters separate the colon and semicolon. 

The make utility uses the suffixes of targets and their prerequisites to infer how a target can be 
made up-to-date. A list of inference rules defines the commands to be executed. By default, make 
contains a built-in set of inference rules. Additional rules can be specified in the makefile. 

The special target .SUFFIXES contains as its prerequisites a list of suffixes that shall be used by I 
the inference rules. The order in which the suffixes are specified defines the order in which the 
inference rules for the suffixes are used. New suffixes shall be appended to the current list by 
specifying a .SUFFIXES special target in the makefile. A .SUFFIXES target with no prerequisites 
shall clear the list of suffixes. An empty .SUFFIXES target followed by a new .SUFFIXES list is 
required to change the order of the suffixes. 

Normally, the user would provide an inference rule for each suffix. The inference rule to update 
a target with a suffix .si from a prerequisite with a suffix .s2 is specified as a target .s2.sl. The 
internal macros provide the means to specify general inference rules (see Internal Macros on 
page 652). 

When no target rule is found to update a target, the inference rules shall be checked. The suffix 
of the target (.si) to be built is compared to the list of suffixes specified by the .SUFFIXES special 
targets. If the .si suffix is found in .SUFFIXES, the inference rules shall be searched in the order 
defined for the first .s2.sl rule whose prerequisite file ($*.82) exists. If the target is out-of-date 
with respect to this prerequisite, the commands for that inference rule shall be executed. 

If the target to be built does not contain a suffix and there is no rule for the target, the single 
suffix inference rules shall be checked. The single-suffix inference rules define how to build a 
target if a file is found with a name that matches the target name with one of the single suffixes 
appended. A rule with one suffix .s2 is the definition of how to build target from target.s2. The 
other suffix (.si) is treated as null. 

xsi A tilde (' ~') in the above rules refers to an SCCS file in the current directory. Thus, the rule .c~.o 
would transform an SCCS C-language source file into an object file (.o). Because the s. of the 
SCCS files is a prefix, it is incompatible with make 's suffix point of view. Hence, the ' ~' is a way 
of changing any file reference into an SCCS file reference. 

Libraries 

If a target or prerequisite contains parentheses, it shall be treated as a member of an archive 
library. For the lib (member. o) expression lib refers to the name of the archive library and member .o I 
to the member name. The application shall ensure that the member is an object file with the .o I 
suffix. The modification time of the expression is the modification time for the member as kept 
in the archive library; see ar on page 168. The .a suffix refers to an archive library. The .s2.a rule 
is used to update a member in the library from a file with a suffix .s2. 
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Internal Macros 

The make utility shall maintain five internal macros that can be used in target and inference rules. 

In order to clearly define the meaning of these macros, some clarification of the terms target rule, 
inference rule, target, and prerequisite is necessary. 

Target rules are specified by the user in a makefile for a particular target. Inference rules are 
user-specified or make-specified rules for a particular class of target name. Explicit prerequisites 
are those prerequisites specified in a makefile on target lines. Implicit prerequisites are those 
prerequisites that are generated when inference rules are used. Inference rules are applied to 
implicit prerequisites or to explicit prerequisites that do not have target rules defined for them in 
the makefile. Target rules are applied to targets specified in the makefile. 

Before any target in the makefile is updated, each of its prerequisites (both explicit and implicit) 
shall be updated. This shall be accomplished by recursively processing each prerequisite. Upon 
recursion, each prerequisite shall become a target itself. Its prerequisites in turn shall be 
processed recursively until a target is found that has no prerequisites, at which point the 
recursion stops. The recursion then shall back up, updating each target as it goes. 

In the definitions that follow, the word target refers to one of: 

• A target specified in the makefile 

• An explicit prerequisite specified in the makefile that becomes the target when make 
processes it during recursion 

• An implicit prerequisite that becomes a target when make processes it during recursion 
In the definitions that follow, the word prerequisite refers to one of the following: 

• An explicit prerequisite specified in the makefile for a particular target 

• An implicit prerequisite generated as a result of locating an appropriate inference rule and 
corresponding file that matches the suffix of the target 

The five internal macros are: 

$@ The $@ shall evaluate to the full target name of the current target, or the archive file I 
name part of a library archive target. It shall be evaluated for both target and inference 
rules. 

For example, in the .c.a inference rule, $@ represents the out-of-date .a file to be built. I 
Similarly, in a makefile target rule to build lib.a from file.c, $@ represents the out-of- I 
date lib.a. I 

$% The $% macro shall be evaluated only when the current target is an archive library I 
member of the form libname(member. o). In these cases, $@ shall evaluate to libname and I 
$% shall evaluates to member. o. The $% macro shall be evaluated for both target and I 
inference rules. 

For example, in a makefile target rule to build lib.a(file.o), $% represents file.o, as I 
opposed to $@, which represents lib.a. I 

$? The $? macro shall evaluate to the list of prerequisites that are newer than the current I 

target. It shall be evaluated for both target and inference rules. 

For example, in a makefile target rule to build prog from filel.o, file2.o, and file3.o, and 
where prog is not out of date with respect to filel.o, but is out of date with respect to 
file2.o and file3.o, $? represents file2.o and file3.o. I 
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In an inference rule, the $< macro shall evaluate to the file name whose existence I 
allowed the inference rule to be chosen for the target. In the .DEFAULT rule, the $< I 
macro shall evaluate to the current target name. The meaning of the $< macro macro is I 
otherwise unspecified. I 

For example, in the .c.a inference rule, $< represents the prerequisite .c file. I 

The $* macro shall evaluate to the current target name with its suffix deleted. It shall be I 
evaluated at least for inference rules. 

For example, in the .c.a inference rule, $*.o represents the out-of-date .o file that I 
corresponds to the prerequisite .c file. 

Each of the internal macros has an alternative form. When an uppercase ' D' or ' F' is appended 
to any of the macros, the meaning is changed to the directory part for ' D' and file name part for 
' F'. The directory part is the path prefix of the file without a trailing slash; for the current 
directory, the directory part is ' .'. When the $? macro contains more than one prerequisite file I 
name, the $(?D) and $(?F) (or ${?D} and ${?F}) macros expand to a list of directory name parts I 
and file name parts respectively. 

For the target lib (member. o) and the s2.a rule, the internal macros are defined as: 

$ < member.s2 

$ * member 

$@ lib 

$ ? member. s2 

$ % member .o 

Default Rules 

The default rules for make shall achieve results that are the same as if the following were used. 
Implementations that do not support the C-Language Development Utilities option may omit 
CC, CFLAGS, YACC, YFLAGS, LEX, LFLAGS, LDFLAGS, and the .c, .y, and .1 inference rules. 
Implementations that do not support FORTRAN may omit FC, FFLAGS, and the .f inference 
rules. Implementations may provide additional macros and rules. 

SPECIAL TARGETS 


Utilities 

$< 

$* 


xsi . SCCS_GET: sees $(SCCSFLAGS) get $ (SCCSGETFLAGS) $@ 

xsi .SUFFIXES: .o .c .y .1 .a . sh .f ,c~ .y~ .1“ .sh~ ,f~ 

MACROS 

MAKE=make 

AR=ar 

ARFLAGS=—rv 

YACC=yacc 

YFLAGS= 

LEX=lex 

LFLAGS= 

LDFLAGS= 

CC=c8 9 
CFLAGS=—O 
FC=fort77 
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FFLAGS=—O 1 
xsi GET=get 
GFLAGS= 

SCCSFLAGS= 

SCCSGETFLAGS=—s 

SINGLE SUFFIX RULES 

. c: 

$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< 

. f: 

$ (FC) $(FFLAGS) $(LDFLAGS) -o $@ $< 

. sh : 

cp $< $@ 
chmod a+x $@ 

xsi . c ~ : 

$(GET) $(GFLAGS) -p $< > $*.c 

$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c 

. f ' : 

$(GET) $(GFLAGS) -p $< > $*.f 
$(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f 

. sh~ : 

$(GET) $(GFLAGS) -p $< > $*.sh 
cp $*.sh $@ 
chmod a+x $@ 

DOUBLE SUFFIX RULES 

. c . o : 

$(CC) $(CFLAGS) -c $< 

. f . o : 

$(FC) $(FFLAGS) -c $< 

•Y-o: 

$(YACC) $(YFLAGS) $< 

$(CC) $(CFLAGS) -c y.tab.c 
rm —f y.tab.c 
mv y.tab.o $@ 

. 1. o : 

$(LEX) $(LFLAGS) $< 

$(CC) $(CFLAGS) -c lex.yy.c 
rm —f lex.yy.c 
mv lex.yy.o $@ 

•Y-c: 

$(YACC) $(YFLAGS) $< 
mv y.tab.c $@ 

. 1. c : 

$(LEX) $(LFLAGS) $< 
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mv lex.yy.c $@ 
xsi . c ~ . o : 

$(GET) $(GFLAGS) -p $< > $*.c 
$(CC) $(CFLAGS) -c $*.c 

. f ~ . o : 

$(GET) $(GFLAGS) -p $< > $*.f 
$(FC) $(FFLAGS) -c $*.f 

•y~-o: 

$(GET) $(GFLAGS) -p $< > $*.y 
$(YACC) $(YFLAGS) $*.y 
$(CC) $(CFLAGS) -c y.tab.c 
rm — f y.tab.c 
mv y.tab.o $@ 

. 1 ~ . o : 

$(GET) $(GFLAGS) -p $< > $*.l 
$(LEX) $(LFLAGS) $*.l 
$(CC) $(CFLAGS) -c lex.yy.c 
rm — f lex.yy.c 
mv lex.yy.o $@ 

•y~-c: 

$(GET) $(GFLAGS) -p $< > $*.y 
$(YACC) $(YFLAGS) $*.y 
mv y.tab.c $@ 

. 1 ~ . c : 

$(GET) $(GFLAGS) -p $< > $*.l 
$(LEX) $(LFLAGS) $*.l 
mv lex.yy.c $@ 


$(CC) -c $(CFLAGS) $< 

$(AR) $(ARFLAGS) $@ $*.o 
rm —f $*.o 

. f . a : 

$(FC) -c $(FFLAGS) $< 

$(AR) $(ARFLAGS) $@ $*.o 
rm —f $*.o 

EXIT STATUS 

When the -q option is specified, the make utility shall exit with one of the following values: 

0 Successful completion. 

1 The target was not up-to-date. 

>1 An error occurred. 

When the -q option is not specified, the make utility shall exit with one of the following values: 
0 Successful completion. 

>0 An error occurred. 
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25098 CONSEQUENCES OF ERRORS 

25099 Default. 

25100 APPLICATION USAGE 

25101 If there is a source file (such as ./source.c) and there are two SCCS files corresponding to it 

25102 (./s.source.c and ./SCCS/s.source.c), on XSI-conformant systems make uses the SCCS file in the 

25103 current directory. However, users are advised to use the underlying SCCS utilities (admin, delta, 

25104 get, and so on) or the sees utility for all source files in a given directory. If both forms are used for 

25105 a given source file, future developers are very likely to be confused. 

25106 It is incumbent upon portable makefiles to specify the .POSIX special target in order to 

25107 guarantee that they are not affected by local extensions. 

25108 The -k and -S options are both present so that the relationship between the command line, the 

25109 MAKEFLAGS variable, and the makefile can be controlled precisely. If the k flag is passed in 

25110 MAKEFLAGS and a command is of the form: 

25111 $ (MAKE) -S foo 

25112 then the default behavior is restored for the child make. 

25113 When the -n option is specified, it is always added to MAKEFLAGS. This allows a recursive 

25114 make -n target to be used to see all of the action that would be taken to update target. 

25115 Because of widespread historical practice, interpreting a ' #' number sign inside a variable as 

25116 the start of a comment has the unfortunate side effect of making it impossible to place a number 

25117 sign in a variable, thus forbidding something like: 

25118 CFLAGS = "-D COMMENT_CHAR=' #' " 

25119 Many historical make utilities stop chaining together inference rules when an intermediate target 

25120 is nonexistent. For example, it might be possible for a make to determine that both .y.c and .c.o 

25121 could be used to convert a .y to a .o. Instead, in this case, make requires the use of a .y.o rule. 

25122 The best way to provide portable makefiles is to include all of the rules needed in the makefile 

25123 itself. The rules provided use only features provided by other parts of this volume of 

25124 IEEE Std. 1003.1-200x. The default rules include rules for optional commands in this volume of 

25125 IEEE Std. 1003.1-200x. Only rules pertaining to commands that are provided are needed in an 

25126 implementation's default set. 

25127 Macros used within other macros are evaluated when the new macro is used rather than when 

25128 the new macro is defined. Therefore: 

25129 MACRO = value 1 

25130 NEW = $ (MACRO) 

25131 MACRO = value2 

25132 target: 

25133 echo $ (NEW) 

25134 would produce value2 and not valuel since NEW was not expanded until it was needed in the 

25135 echo command line. 

25136 Some historical applications have been known to intermix target_name and macro=name operands 

25137 on the command line, expecting that all of the macros are processed before any of the targets are 

25138 dealt with. Portable applications do not do this, although some backward compatibility support 

25139 may be included in some implementations. 

25140 The following characters in file names may give trouble: ' =', ' :', ' '', ' ' ', and ' @'. For 

25141 inference rules, the description of $< and $? seem similar. However, an example shows the I 
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25142 

minor difference. In a makefile containing: 

25143 

f oo 

. o: foo.h 

25144 

25145 

25146 

if foo.h is newer than foo.o, yet foo.c is older than foo.o, the built-in rule to make foo.o from 
foo.c is used, with $< equal to foo.c and $? equal to foo.h. If foo.c is also newer than foo.o, $< is 
equal to foo.c and $? is equal to foo.h foo.c. 

25147 EXAMPLES 


25148 

1. 

The following command: 

25149 


make 

25150 


makes the first target found in the makefile. 

25151 

2. 

The following command: 

25152 


make junk 

25153 


makes the target junk. 

25154 

25155 

3 . 

The following makefile says that pgm depends on two files, a.o and b.o, and that they in 
turn depend on their corresponding source files (a.c and b.c), and a common file incl.h: 

25156 

25157 

25158 

25159 

25160 

25161 


pgm: a.o b.o 

c89 a.o b.o —o pgm 

a. o: incl.h a.c 

c89 —c a.c 

b. o: incl.h b.c 

c89 -c b.c 

25162 

4 . 

An example for making optimized .o files from .c files is: 

25163 

25164 


. c . o : 

c89 —c —0 $*.c 

25165 


or: 

25166 

25167 


. c . o : 

c89 -c -0 $< 

25168 

25169 

5 . 

The most common use of the archive interface follows. Here, it is assumed that the source 
files are all C-language source: 

25170 

25171 


lib: lib(filel.o) lib(file2.o) lib(file3.o) 

@echo lib is now up-to-date 

25172 


The .c.a rule is used to make filel.o, file2.o, and file3.o and insert them into lib. 

25173 

25174 


The treatment of escaped <newline> characters throughout the makefile is historical 
practice. For example, the inference rule: 

25175 

25176 


. c. o\ 

25177 


works, and the macro: 

25178 

25179 

25180 

25181 


f= bar baz\ 
biz 

a: 

echo ==$f== 
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25189 

25190 
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25192 

25193 

25194 

25195 

25196 

25197 

25198 

25199 

25200 

25201 

25202 

25203 

25204 

25205 

25206 

25207 

25208 

25209 

25210 

25211 

25212 

25213 

25214 

25215 

25216 

25217 

25218 

25219 

25220 

25221 

25222 


echoes "==bar baz biz==". 

If $? were: I 

/usr/include/stdio.h /usr/include/unistd.h foo.h 

then $(?D) would be: I 

/usr/include /usr/include . 

and $(?F) would be: I 

stdio.h unistd.h foo.h 

6. The contents of the built-in rules can be viewed by running: 

make —p —f /dev/null 2>/dev/null 

RATIONALE 

The make utility described in this volume of IEEE Std. 1003.1-200x is intended to provide the 
means for changing portable source code into executables that can be run on a 
IEEE Std. 1003.1-200x-conforming system. It reflects the most common features present in 
System V and BSD make s. 

Historically, the make utility has been an especially fertile ground for vendor and research 
organization-specific syntax modifications and extensions. Examples include: 

• Syntax supporting parallel execution (such as from various multiprocessor vendors, GNU, 
and others) 

• Additional "operators" separating targets and their prerequisites (System V, BSD, and 
others) 

• Specifying that command lines containing the strings ${MAKE} and $(MAKE) are executed 
when the -n option is specified (GNU and System V) 

• Modifications of the meaning of internal macros when referencing libraries (BSD and others) 

• Using a single instance of the shell for all of the command lines of the target (BSD and others) 

• Allowing spaces as well as tabs to delimit command lines (BSD) 

• Adding C preprocessor-style "include" and "ifdef" constructs (System V, GNU, BSD, and 
others) 

• Remote execution of command lines (Sprite and others) 

• Specifying additional special targets (BSD, System V, and most others) 

Additionally, many vendors and research organizations have rethought the basic concepts of 
make, creating vastly extended, as well as completely new, syntaxes. Each of these versions of 
make fulfills the needs of a different community of users; it is unreasonable for this volume of 
IEEE Std. 1003.1-200x to require behavior that would be incompatible (and probably inferior) to 
historical practice for such a community. 

In similar circumstances, when the industry has enough sufficiently incompatible formats as to 
make them irreconcilable, this volume of IEEE Std. 1003.1-200x has followed one or both of two 
courses of action. Commands have been renamed (cksum, echo, and pax) and/or command line I 
options have been provided to select the desired behavior (grep, od, and pax). I 

Because the syntax specified for the make utility is, by and large, a subset of the syntaxes 
accepted by almost all versions of make, it was decided that it would be counter-productive to 
change the name. And since the makefile itself is a basic unit of portability, it would not be 
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completely effective to reserve a new option letter, such as make -P, to achieve the portable 
behavior. Therefore, the special target .POSIX was added to the makefile, allowing users to 
specify "standard" behavior. This special target does not preclude extensions in the make utility, 
nor does it preclude such extensions being used by the makefile specifying the target; it does, 
however, preclude any extensions from being applied that could alter the behavior of previously 
valid syntax; such extensions must be controlled via command line options or new special I 
targets. It is incumbent upon portable makefiles to specify the .POSIX special target in order to I 
guarantee that they are not affected by local extensions. 

The portable version of make described in this reference page is not intended to be the state-of- 
the-art software generation tool and, as such, some newer and more leading-edge features have 
not been included. An attempt has been made to describe the portable makefile in a manner that 
does not preclude such extensions as long as they do not disturb the portable behavior described 
here. 

When the -n option is specified, it is always added to MAKEFLAGS. This allows a recursive 
make -n target to be used to see all of the action that would be taken to update target. 

The definition of MAKEFLAGS allows both the System V letter string and the BSD command line I 
formats. The two formats are sufficiently different to allow implementations to support both 
without ambiguity. 

Early proposals stated that an "unquoted" number sign was treated as the start of a comment. 
The make utility does not pay any attention to quotes. A number sign starts a comment 
regardless of its surroundings. 

The text about "other implementation-dependent path names may also be tried" in addition to 
./makefile and ./Makefile is to allow such extensions as SCCS/s.Makefile and other variations. 

It was made an implementation-dependent requirement (as opposed to unspecified behavior) to 
highlight surprising implementations that might select something unexpected like 
/etc/Makefile. 

Early proposals contained the macro NPROC as a means of specifying that make should use n 
processes to do the work required. While this feature is a valuable extension for many systems, it 
is not common usage and could require other non-trivial extensions to makefile syntax. This 
extension is not required by this volume of IEEE Std. 1003.1-200x, but could be provided as a 
compatible extension. The macro PARALLEL is used by some historical systems with essentially 
the same meaning (but without using a name that is a common system limit value). It is 
suggested that implementors recognize the existing use of NPROC and/or PARALLEL as 
extensions to make. 

The default rules are based on System V. The default CC= value is c89 instead of cc because this 
volume of IEEE Std. 1003.1-200x does not standardize the utility named cc. Thus, every 
conforming application would be required to define CC =c89 to expect to run. There is no 
advantage conferred by the hope that the makefile might hit the "preferred" compiler because 
this cannot be guaranteed to work. Also, since the portable makescript can only use the c89 
options, no advantage is conferred in terms of what the script can do. It is a quality-of- 
implementation issue as to whether c89 is as valuable as cc. 

The -d option to make is frequently used to produce debugging information, but is too 
implementation-dependent to add to this volume of IEEE Std. 1003.1-200x. 

The -p option is not passed in MAKEFLAGS on most historical implementations and to change 
this would cause many implementations to break without sufficiently increased portability. 

Commands that begin with a plus sign (' +') are executed even if the -n option is present. Based 
on the GNU version of make, the behavior of -n when the plus-sign prefix is encountered has 
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been extended to apply to -q and -t as well. However, the System V convention of forcing 
command execution with -n when the command line of a target contains either of the strings 
$(MAKE) or ${MAKE} has not been adopted. This functionality appeared in early proposals, but 
the danger of this approach was pointed out with the following example of a portion of a 
makefile: 

subdir: 

cd subdir; rm all_the_files; $(MAKE) 

The loss of the System V behavior in this case is well-balanced by the safety afforded to other 
makefiles that were not aware of this situation. In any event, the command line plus-sign prefix I 
can provide the desired functionality. I 

The double colon in the target rule format is supported in BSD systems to allow more than one 
target line containing the same target name to have commands associated with it. Since this is 
not functionality described in the SVID or XPG3 it has been allowed as an extension, but not 
mandated. 

The default rules are provided with text specifying that the built-in rules shall be the same as if I 
the listed set were used. The intent is that implementations should be able to use the rules 
without change, but will be allowed to alter them in ways that do not affect the primary 
behavior. 

The best way to provide portable makefiles is to include all of the rules needed in the makefile 
itself. The rules provided use only features provided by other portions of this volume of 
IEEE Std. 1003.1-200x. The default rules include rules for optional commands in this volume of 
IEEE Std. 1003.1-200x. Only rules pertaining to commands that are provided are needed in the 
default set of an implementation. 

One point of discussion was whether to drop the default rules list from this volume of 
IEEE Std. 1003.1-200x. They provide convenience, but do not enhance portability of applications. 
The prime benefit is in portability of users who wish to type make command and have the 
command build from a command.c file. 

The historical MAKESHELL feature was omitted. In some implementations it is used to let a user 
override the shell to be used to run make commands. This was confusing; for a portable make, the 
shell should be chosen by the makefile writer or specified on the make command line and not by 
a user running make. 

The make utilities in most historical implementations process the prerequisites of a target in left- 
to-right order, and the makefile format requires this. It supports the standard idiom used in 
many makefiles that produce yacc programs; for example: 

foo: y.tab.o lex.o main.o 

$(CC) $(CFLAGS) —o $@ t.tab.o lex.o main.o 

In this example, if make chose any arbitrary order, the lex.o might not be made with the correct 
y.tab.h. Although there may be better ways to express this relationship, it is widely used 
historically. Implementations that desire to update prerequisites in parallel should require an 
explicit extension to make or the makefile format to accomplish it, as described previously. 

The algorithm for determining a new entry for target rules is partially unspecified. Some 
historical make s allow blank, empty, or comment lines within the collection of commands 
marked by leading <tab>s. A conforming makefile must ensure that each command starts with 
a <tab>, but implementations are free to ignore blank, empty, and comment lines without 
triggering the start of a new entry. 
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The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, along with 
the more traditional SIGINT and SIGQUIT, remove the current target unless directed not to do 
so. SIGTERM and SIGHUP were added to parallel other utilities that have historically cleaned 
up their work as a result of these signals. When make receives any signal other than SIGQUIT, it 
is required to resend itself the signal it received so that it exits with a status that reflects the 
signal. The results from SIGQUIT are partially unspecified because, on systems that create core 
files upon receipt of SIGQUIT, the core from make would conflict with a core file from the 
command that was running when the SIGQUIT arrived. The main concern was to prevent 
damaged files from appearing up-to-date when make is rerun. 

The .PRECIOUS special target was extended to affect all targets globally (by specifying no 
prerequisites). The .IGNORE and .SILENT special targets were extended to allow prerequisites; 
it was judged to be more useful in some cases to be able to turn off errors or echoing for a list of 
targets than for the entire makefile. These extensions to the make in System V were made to 
match historical practice from the BSD make. 

Macros are not exported to the environment of commands to be run. This was never the case in 
any historical make and would have serious consequences. The environment is the same as the 
environment to make except that MAKEFLAGS and macros defined on the make command line 
are added. 

Some implementations do not use system () for all command lines, as required by the portable 
makefile format; as a performance enhancement, they select lines without shell metacharacters 
for direct execution by execve( ). There is no requirement that system () be used specifically, but 
merely that the same results be achieved. The metacharacters typically used to bypass the direct 
execve( ) execution have been any of: 

= 1 (>;&<>*?[] \ \n 

The default in some advanced versions of make is to group all the command lines for a target and 
execute them using a single shell invocation; the System V method is to pass each line 
individually to a separate shell. The single-shell method has the advantages in performance and 
the lack of a requirement for many continued lines. However, converting to this newer method 
has caused portability problems with many historical makefiles, so the behavior with the POSIX 
makefile is specified to be the same as that of System V. It is suggested that the special target 
.ONESHELL be used as an implementation extension to achieve the single-shell grouping for a 
target or group of targets. 

Novice users of make have had difficulty with the historical need to start commands with a 
<tab> character. Since it is often difficult to discern differences between <tab> and <space> 
characters on terminals or printed listings, confusing bugs can arise. In early proposals, an 
attempt was made to correct this problem by allowing leading <blank>s instead of <tab>s. 
However, implementors reported many makefiles that failed in subtle ways following this 
change, and it is difficult to implement a make that unambiguously can differentiate between 
macro and command lines. There is extensive historical practice of allowing leading spaces 
before macro definitions. Forcing macro lines into column 1 would be a significant backwards- 
compatibility problem for some makefiles. Therefore, historical practice was restored. 

The System V INCLUDE feature was considered, but not included. This would treat a line that 
began in the first column and contained INCLUDE <filename> as an indication to read <filename> 
at that point in the makefile. This is difficult to use in a portable way, and it raises concerns 
about nesting levels and diagnostics. System V, BSD, GNU, and others have used different 
methods for including files. 

The System V dynamic dependency feature was not included. It would support: 
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25362 cat: $$@.c 

25363 that would expand to; 

25364 cat : cat. c 

25365 This feature exists only in the new version of System V make and, while useful, is not in wide 

25366 usage. This means that macros are expanded twice for prerequisites: once at makefile parse time 

25367 and once at target update time. 

25368 Consideration was given to adding metarules to the POSIX make. This would make %.o: %.c the 

25369 same as .c.o:. This is quite useful and available from some vendors, but it would cause too many 

25370 changes to this make to support. It would have introduced rule chaining and new substitution 

25371 rules. However, the rules for target names have been set to reserve the ' %' and ' ' characters. 

25372 These are traditionally used to implement metarules and quoting of target names, respectively. 

25373 Implementors are strongly encouraged to use these characters only for these purposes. 

25374 A request was made to extend the suffix delimiter character from a period to any character. The 

25375 metarules feature in newer make s solves this problem in a more general way. This volume of 

25376 IEEE Std. 1003.1-200x is staying with the more conservative historical definition. 

25377 The standard output format for the -p option is not described because it is primarily a 

25378 debugging option and because the format is not generally useful to programs. In historical 

25379 implementations the output is not suitable for use in generating makefiles. The -p format has 

25380 been variable across historical implementations. Therefore, the definition of -p was only to 

25381 provide a consistently named option for obtaining make script debugging information. 

25382 Some historical implementations have not cleared the suffix list with -r. 

25383 Implementations should be aware that some historical applications have intermixed target_name 

25384 and macro-value operands on the command line, expecting that all of the macros are processed 

25385 before any of the targets are dealt with. Portable applications do not do this, but some 

25386 backwards-compatibility support may be warranted. 

25387 Empty inference rules are specified with a semicolon command rather than omitting all 

25388 commands, as described in an early proposal. The latter case has no traditional meaning and is 

25389 reserved for implementation extensions, such as in GNU make. 

25390 FUTURE DIRECTIONS 

25391 None. 

25392 SEE ALSO 

25393 ar, c89, get, lex, sh, yacc, the System Interfaces volume of IEEE Std. 1003.1-200x, system () 

25394 CHANGE HISTORY 

25395 First released in Issue 2. 

25396 Issue 4 

25397 Aligned with the ISO/IEC 9945-2:1993 standard. 

25398 Issue 4, Version 2 

25399 Under Default Rules, the string G$ @" is deleted from the line referencing sees. 

25400 Issue 5 

25401 FUTURE DIRECTIONS section added. 


25402 Issue 6 

25403 This utility is now marked as part of the Software Development Utilities option. 


25404 The Open Group corrigenda item U029/1 has been applied, correcting a typographical error in 

25405 the SPECIAL TARGETS section. 
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25411 


In the ENVIRONMENT VARIABLES section, the PROJECTDIR description is updated from 
"otherwise, the home directory of a user of that name is examined" to "otherwise, the value of 
PROJECTDIR is treated as a user name and that useds initial working directory is examined". I 

It is specified whether the command line is related to the makefile or to the make command, and I 
the macro processing rules are updated to align with the IEEE P1003.2b draft standard. I 

The normative text is reworded to avoid use of the term "must" for application requirements. I 
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NAME 

man — display system documentation 

SYNOPSIS 

man [—k] name... 

DESCRIPTION 

The man utility shall write information about each of the name operands. If name is the name of a 
standard utility, man at a minimum shall write a message describing the syntax used by the 
standard utility, its options, and operands. If more information is available, the man utility shall 
provide it in an implementation-dependent manner. 

An implementation may provide information for values of name other than the standard utilities. 
Standard utilities that are listed as optional and that are not supported by the implementation 
either shall cause a brief message indicating that fact to be displayed or shall cause a full display 
of information as described previously. 

OPTIONS 

The man utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following option shall be supported: 

-k Interpret name operands as keywords to be used in searching a utilities summary 
database that contains a brief purpose entry for each standard utility and write lines 
from the summary database that match any of the keywords. The keyword search shall 
produce results that are the equivalent of the output of the following command: 

grep —Ei ' 

name 

name 

' summary-database 

This assumes that the summary-database is a text file with a single entry per line; this 
organization is not required and the example using grey -Ei is merely illustrative of the 
type of search intended. The purpose entry to be included in the database shall consist 
of a terse description of the purpose of the utility. 

OPERANDS 

The following operand shall be supported: 

name A keyword or the name of a standard utility. When -k is not specified and name 

does not represent one of the standard utilities, the results are unspecified. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of man: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 
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25457 

25458 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


25459 

25460 

25461 

25462 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and in the summary database). The value of LC_CTYPE need not affect 
the format of the information written about the name operands. 


25463 LC_MESSAGES 

25464 Determine the locale that should be used to affect the format and contents of 

25465 diagnostic messages written to standard error and informative messages written to 

25466 standard output. 

25467 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

25468 PAGER Determine an output filtering command for writing the output to a terminal. Any 

25469 string acceptable as a commandjstring operand to the sh -c command shall be valid. 

25470 When standard output is a terminal device, the reference page output shall be 

25471 piped through the command. If the PAGER variable is null or not set, the 

25472 command shall be either more or another paginator utility documented in the 

25473 system documentation. 


25474 ASYNCHRONOUS EVENTS 

25475 Default. 


25476 STDOUT 

25477 The man utility shall write text describing the syntax of the utility name, its options and its 

25478 operands, or, when -k is specified, lines from the summary database. The format of this text is 

25479 implementation-dependent. 

25480 STDERR 

25481 Used only for diagnostic messages. 

25482 OUTPUT FILES 

25483 None. 


25484 EXTENDED DESCRIPTION 

25485 None. 


25486 EXIT STATUS 

25487 The following exit values shall be returned: 

25488 0 Successful completion. 

25489 >0 An error occurred. 


25490 CONSEQUENCES OF ERRORS 

25491 Default. 

25492 APPLICATION USAGE 

25493 None. 

25494 EXAMPLES 

25495 None. 

25496 RATIONALE 

25497 It is recognized that the man utility is only of minimal usefulness as specified. The opinion of the 

25498 standard developers was strongly divided as to how much or how little information man should 

25499 be required to provide. They considered, however, that the provision of some portable way of 

25500 accessing documentation would aid user portability. The arguments against a fuller 
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25501 specification were: 

25502 • Large quantities of documentation should not be required on a system that does not have 

25503 excess disk space. 

25504 • The current manual system does not present information in a manner that greatly aids user 

25505 portability. 

25506 • A "better help system" is currently an area in which vendors feel that they can add value to 

25507 their POSIX implementations. 

25508 The -f option was considered, but due to implementation differences, it was not included in this 

25509 volume of IEEE Std. 1003.1-200x. 

25510 The description was changed to be more specific about what has to be displayed for a utility. 

25511 The standard developers considered it insufficient to allow a display of only the synopsis 

25512 without giving a short description of what each option and operand does. 

25513 The "purpose" entry to be included in the database can be similar to the section title (less the 

25514 numeric prefix) from this volume of IEEE Std. 1003.1-200x for each utility. These titles are 

25515 similar to those used in historical systems for this purpose. 

25516 See mailx for rationale concerning the default paginator. 

25517 The caveat in the LC_CTYPE description was added because it is not a requirement that an 

25518 implementation provide reference pages for all of its supported locales on each system; 

25519 changing LC_CTYPE does not necessarily translate the reference page into another language. 

25520 This is equivalent to the current state of LC_MESSAGES in IEEE Std. 1003.1-200x—locale-specific 

25521 messages are not yet a requirement. 

25522 The historical MANPATH variable is not included in POSIX because no attempt is made to 

25523 specify naming conventions for reference page files, nor even to mandate that they are files at 

25524 all. In some systems they could be a true database, a hypertext file, or even fixed strings within 

25525 the man executable. The standard developers considered the portability of reference pages to be 

25526 outside their scope of work (and more appropriate to the POSIX.7 working group developing 

25527 application-installation tools). However, users should be aware that MANPATH is implemented 

25528 on a number of historical systems and that it can be used to tailor the search pattern for reference 

25529 pages from the various categories (utilities, functions, file formats, and so on) when the system 

25530 administrator reveals the location and conventions for reference pages on the system. 

25531 The keyword search can rely on at least the text of the section titles from these utility 

25532 descriptions, and the implementation may add more keywords. The term "section titles" refers 

25533 to the strings such as: 

25534 man — Display system documentation 

25535 ps — Report process status 

25536 FUTURE DIRECTIONS 

25537 None. 

25538 SEE ALSO 

25539 more 

25540 CHANGE HISTORY 

25541 First released in Issue 4. 
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25542 Issue 5 

25543 FUTURE DIRECTIONS section added. 
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25544 NAME 

25545 mesg — permit or deny messages 

25546 SYNOPSIS 

25547 up mesg [y I n] 

25548 

25549 DESCRIPTION 

25550 The mesg utility shall control whether other users are allowed to send messages via write, talk, or 

25551 other utilities to a terminal device. The terminal device affected shall be determined by searching 

25552 for the first terminal in the sequence of devices associated with standard input, standard output, 

25553 and standard error, respectively. With no arguments, mesg shall report the current state without 

25554 changing it. Processes with appropriate privileges may be able to send messages to the terminal 

25555 independent of the current state. 

25556 OPTIONS 

25557 None. 

25558 OPERANDS 

25559 The following operands shall be supported in the POSIX locale: 

25560 y Grant permission to other users to send messages to the terminal device. 

25561 n Deny permission to other users to send messages to the terminal device. 

25562 STDIN 

25563 Not used. 

25564 INPUT FILES 

25565 None. 


25566 ENVIRONMENT VARIABLES 

25567 The following environment variables shall affect the execution of mesg: 


25568 

25569 

25570 

25571 

25572 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


25573 LC_ALL If set to a non-empty string value, override the values of all the other 

25574 internationalization variables. 


25575 

25576 

25577 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


25578 LC_MESSAGES 

25579 Determine the locale that should be used to affect the format and contents of 

25580 diagnostic messages written (by mesg) to standard error. 


25581 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


25582 ASYNCHRONOUS EVENTS 

25583 Default. 


25584 STDOUT 

25585 If no operand is specified, mesg shall display the current terminal state in an unspecified format. 
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25586 STDERR 

25587 Used only for diagnostic messages. 

25588 OUTPUT FILES 

25589 None. 

25590 EXTENDED DESCRIPTION 

25591 None. 

25592 EXIT STATUS 

25593 The following exit values shall be returned: 

25594 0 Receiving messages is allowed. 

25595 1 Receiving messages is not allowed. 

25596 >1 An error occurred. 

25597 CONSEQUENCES OF ERRORS 

25598 Default. 

25599 APPLICATION USAGE 

25600 The mechanism by which the message status of the terminal is changed is unspecified. 

25601 Therefore, unspecified actions may cause the status of the terminal to change after mesg has 

25602 successfully completed. These actions may include, but are not limited to: another invocation of 

25603 the mesg utility, login procedures; invocation of the stty utility, invocation of the climod utility or 

25604 chmod{) function, and so on. 

25605 Application writers should note that this utility need not be provided on systems that do not 

25606 support the User Portability Utilities option. 

25607 EXAMPLES 

25608 None. 

25609 RATIONALE 

25610 The terminal changed by mesg is that associated with the standard input, output, or error, rather 

25611 than the controlling terminal for the session. This is because users logged in more than once 

25612 should be able to change any of their login terminals without having to stop the job running in 

25613 those sessions. This is not a security problem involving the terminals of other users because 

25614 appropriate privileges would be required to affect the terminal of another user. 

25615 The method of checking each of the first three file descriptors in sequence until a terminal is 

25616 found was adopted from System V. 

25617 The file /dev/tty is not specified for the terminal device because it was thought to be too 

25618 restrictive. Typical environment changes for the n operand are that write permissions are 

25619 removed for others and group from the appropriate device. It was decided to leave the actual 

25620 description of what is done as unspecified because of potential differences between 

25621 implementations. 

25622 The format for standard output is unspecified because of differences between historical 

25623 implementations. This output is generally not useful to shell scripts (they can use the exit 

25624 status), so exact parsing of the output is unnecessary. 

25625 FUTURE DIRECTIONS 

25626 None. 
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25627 SEE ALSO 

25628 talk, ivrite 

25629 CHANGE HISTORY 

25630 First released in Issue 2. 

25631 Issue 4 

25632 Aligned with the ISO/IEC 9945-2:1993 standard. 

25633 Issue 6 

25634 This utility is now marked as part of the User Portability Utilities option. 
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25635 NAME 

25636 mkdir — make directories 


25637 SYNOPSIS 

25638 mkdir [—p] [— m mode ] dir. . . 

25639 DESCRIPTION 

25640 The mkdir utility shall create the directories specified by the operands, in the order specified. 

25641 For each dir operand, the mkdir utility shall perform actions equivalent to the mkdir () function 

25642 defined in the System Interfaces volume of IEEE Std. 1003.1-200x, called with the following 

25643 arguments: 

25644 1. The dir operand is used as the path argument. 

25645 2. The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO is used as 

25646 the mode argument. (If the -m option is specified, the mode option-argument overrides this 

25647 default.) 


25648 OPTIONS 

25649 The mkdir utility shall conform to the System Interface Definitions volume of I 

25650 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

25651 The following options shall be supported: 


25652 

25653 

25654 

25655 

25656 

25657 


-m mode Set the file permission bits of the newly-created directory to the specified mode 
value. The mode option-argument shall be the same as the mode operand defined 
for the chmod utility. In the symbolic_mode strings, the op characters ' +' and 
shall be interpreted relative to an assumed initial mode of a=rzvx ; ' +' shall add 
permissions to the default mode, shall delete permissions from the default 
mode. 


25658 

25659 

25660 

25661 

25662 

25663 

25664 

25665 


Create any missing intermediate path name components. 

For each dir operand that does not name an existing directory, effects equivalent to 
those caused by the following command shall occur: 

mkdir —p —m $(umask —S),u+wx $(dirname dir) && 
mkdir [—m mode] dir 

where the -m mode option represents that option supplied to the original 
invocation of mkdir, if any. 

Each dir operand that names an existing directory shall be ignored without error. 


25666 OPERANDS 

25667 The following operand shall be supported: 


25668 dir A path name of a directory to be created. 


25669 STDIN 

25670 Not used. 


25671 INPUT FILES 

25672 None. 


25673 ENVIRONMENT VARIABLES 

25674 The following environment variables shall affect the execution of mkdir: 

25675 LANG Provide a default value for the internationalization variables that are unset or null. 

25676 If LANG is unset or null, the corresponding value from the implementation- 

25677 dependent default locale shall be used. If any of the internationalization variables 
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25678 contains an invalid setting, the utility shall behave as if none of the variables had 

25679 been defined. 

25680 LC_ALL If set to a non-empty string value, override the values of all the other 

25681 internationalization variables. 

25682 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

25683 characters (for example, single-byte as opposed to multi-byte characters in 

25684 arguments). 

25685 LC_MESSAGES 

25686 Determine the locale that should be used to affect the format and contents of 

25687 diagnostic messages written to standard error. 

25688 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

25689 ASYNCHRONOUS EVENTS 

25690 Default. 

25691 STDOUT 

25692 Not used. 

25693 STDERR 

25694 Used only for diagnostic messages. 

25695 OUTPUT FILES 

25696 None. 

25697 EXTENDED DESCRIPTION 

25698 None. 

25699 EXIT STATUS 

25700 The following exit values shall be returned: 

25701 0 All the specified directories were created successfully or the -p option was specified and all 

25702 the specified directories now exist. 

25703 >0 An error occurred. 

25704 CONSEQUENCES OF ERRORS 

25705 Default. 

25706 APPLICATION USAGE 

25707 The default file mode for directories is a=nvx (777 on most systems) with selected permissions 

25708 removed in accordance with the file mode creation mask. For intermediate path name 

25709 components created by mkdir, the mode is the default modified by n+ivx so that the 

25710 subdirectories can always be created regardless of the file mode creation mask; if different 

25711 ultimate permissions are desired for the intermediate directories, they can be changed 

25712 afterwards with chmod. 

25713 Note that some of the requested directories may have been created even if an error occurs. 

25714 EXAMPLES 

25715 None. 

25716 RATIONALE 

25717 The System V -m option was included to control the file mode. 

25718 The System V -p option was included to create any needed intermediate directories and to 

25719 complement the functionality provided by rmdir for removing directories in the path prefix as 

25720 they become empty. Because no error is produced if any path component already exists, the -p 
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25721 option is also useful to ensure that a particular directory exists. 

25722 The functionality of mkdir is described substantially through a reference to the mkdir () function 

25723 in the System Interfaces volume of IEEE Std. 1003.1-200x. For example, by default, the mode of 

25724 the directory is affected by the file mode creation mask in accordance with the specified 

25725 behavior of the mkdir () function. In this way, there is less duplication of effort required for 

25726 describing details of the directory creation. 

25727 FUTURE DIRECTIONS 

25728 None. 

25729 SEE ALSO 

25730 rm, rmdir, umask, the System Interfaces volume of IEEE Std. 1003.1-200x, mkdir () 

25731 CHANGE HISTORY 

25732 First released in Issue 2. 

25733 Issue 4 

25734 Aligned with the ISO/IEC 9945-2:1993 standard. 

25735 Issue 5 

25736 FUTURE DIRECTIONS section added. 
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25737 NAME 

25738 mkfifo — make FIFO special files 

25739 SYNOPSIS 

25740 mkfifo [— m mode ] file. . . 


25741 DESCRIPTION 

25742 The mkfifo utility shall create the FIFO special files specified by the operands, in the order 

25743 specified. 

25744 For each file operand, the mkfifo utility shall perform actions equivalent to the mkfifo () function 

25745 defined in the System Interfaces volume of IEEE Std. 1003.1-200x, called with the following 

25746 arguments: 


25747 

25748 

25749 

25750 

25751 


1. The file operand is used as the path argument. 

2. The value of the bitwise-inclusive OR of S_IRUSR, SJWUSR, SJRGRP, S_IWGRP, 

S_IROTH, and S_IWOTH is used as the mode argument. (If the -m option is specified, the I 
value of the mkfifo () mode argument is unspecified, but the FIFO shall at no time have I 
permissions less restrictive than the -m mode option-argument.) I 


25752 OPTIONS 

25753 The mkfifo utility shall conform to the System Interface Definitions volume of I 

25754 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

25755 The following option shall be supported: 


25756 

25757 

25758 

25759 


-m mode Set the file permission bits of the newly-created FIFO to the specified mode value. 

The mode option-argument shall be the same as the mode operand defined for the 
chmod utility. In the symbolicjnode strings, the op characters ' +' and shall be 
interpreted relative to an assumed initial mode of a-riv. 


25760 OPERANDS 

25761 The following operand shall be supported: 


25762 file A path name of the FIFO special file to be created. 


25763 STDIN 

25764 Not used. 


25765 INPUT FILES 

25766 None. 


25767 ENVIRONMENT VARIABLES 

25768 The following environment variables shall affect the execution of mkfifo: 


25769 

25770 

25771 

25772 

25773 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


25774 

25775 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


25776 

25777 

25778 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


25779 LC_MESSAGES 

25780 Determine the locale that should be used to affect the format and contents of 
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25781 

25782 

25783 

25784 

25785 

25786 

25787 

25788 

25789 

25790 

25791 

25792 

25793 

25794 

25795 

25796 

25797 

25798 

25799 

25800 

25801 

25802 

25803 

25804 

25805 

25806 

25807 

25808 

25809 

25810 

25811 

25812 

25813 

25814 

25815 

25816 

25817 

25818 

25819 

25820 


diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 All the specified FIFO special files were created successfully. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

This new utility was added to permit shell applications to create FIFO special files. 

The -m option was added to control the file mode, for consistency with the similar 
provided the mkdir utility. 

Early proposals included a -p option similar to the mkdir -p option that created 
directories leading up to the FIFO specified by the final component. This was removed because 
it is not commonly needed and is not common practice with similar utilities. 

The functionality of mkfifo is described substantially through a reference to the mkfifo () function 
in the System Interfaces volume of IEEE Std. 1003.1-200x. For example, by default, the mode of 
the FIFO file is affected by the file mode creation mask in accordance with the specified behavior 
of the mkfifo () function. In this way, there is less duplication of effort required for describing 
details of the file creation. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

umask, the System Interfaces volume of IEEE Std. 1003.1-200x, mkfifo () 

CHANGE HISTORY 

First released in Issue 3. 
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25821 Issue 4 

25822 Aligned with the ISO/IEC 9945-2:1993 standard. 
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25823 

25824 

25825 

25826 

25827 

25828 

25829 

25830 

25831 

25832 

25833 

25834 

25835 

25836 

25837 

25838 

25839 

25840 

25841 

25842 

25843 

25844 

25845 

25846 

25847 

25848 

25849 

25850 

25851 

25852 

25853 

25854 

25855 

25856 

25857 

25858 

25859 

25860 

25861 

25862 

25863 

25864 

25865 

25866 

25867 


NAME 

more — display files on a page-by-page basis 

SYNOPSIS 

UP more [—ceisu][—n number ][—p command ][—t tagstring][file ...] I 

I 

DESCRIPTION 

The more utility shall read files and either write them to the terminal on a page-by-page basis or 
filter them to standard output. If standard output is not a terminal device, all input files shall be 
copied to standard output in their entirety, without modification, except as specified for the -s I 
option. If standard output is a terminal device, the files shall be written a number of lines (one I 
screenful) at a time under the control of user commands. See the EXTENDED DESCRIPTION I 
section. I 

Certain block-mode terminals do not have all the capabilities necessary to support the complete 
more definition; they are incapable of accepting commands that are not terminated with a 
<newline> character. Implementations that support such terminals shall provide an operating I 
mode to more in which all commands can be terminated with a <newline> character on those I 
terminals. This mode: 

• Shall be documented in the system documentation 

• Shall, at invocation, inform the user of the terminal deficiency that requires the <newline> I 
character usage and provide instructions on how this warning can be suppressed in future 
invocations 

• Shall not be required for implementations supporting only fully capable terminals 

• Shall not affect commands already requiring <newline> characters 

• Shall not affect users on the capable terminals from using more as described in this volume of 
IEEE Std. 1003.1-200x 

OPTIONS 

The more utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-c If a screen is to be written that has no lines in common with the current screen, or 

more is writing its first screen, more does not scroll the screen, but instead redraws 
each line of the screen in turn, from the top of the screen to the bottom. In addition, 
if more is writing its first screen, the screen is cleared. This option may be silently I 
ignored on devices with insufficient terminal capabilities. I 

-e By default, more shall exit immediately after writing the last line of the last file in I 

the argument list. If the -e option is specified: I 

1. If there is only a single file in the argument list and that file was completely I 

displayed on a single screen, more shall exit immediately after writing the last I 
line of that file. I 

2. Otherwise, more shall exit only after reaching end-of-file on the last file in the I 

argument list twice without an intervening operation. See the EXTENDED I 
DESCRIPTION section. I 

-i Perform pattern matching in searches without regard to case; see the System I 

Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.2, Regular I 
Expression General Requirements . I 
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25868 

25869 

25870 

25871 

25872 

25873 

25874 

25875 

25876 

25877 

25878 

25879 

25880 

25881 

25882 

25883 

25884 

25885 

25886 

25887 

25888 

25889 

25890 

25891 

25892 

25893 

25894 

25895 

25896 

25897 

25898 

25899 

25900 

25901 

25902 

25903 

25904 

25905 

25906 

25907 

25908 

25909 

25910 

25911 


-n number Specify the number of lines per screenful. The number argument is a positive 
decimal integer. The -n option shall override any values obtained from any other 
source. 

-p command Each time a screen from a new file is displayed or redisplayed (including as a 
result of more commands; for example, :p), execute the more command(s) in the 
command arguments in the order specified, as if entered by the user after the first 
screen has been displayed. No intermediate results shall be displayed (that is, if the 
command is a movement to a screen different than the normal first screen, only the 
screen resulting from the command shall be displayed.) If any of the commands 
fail for any reason, an informational message to this effect shall be written, and no 
further commands specified using the -p option shall be executed for this file. 

-s Behave as if consecutive empty lines were a single empty line. 

-t tagstring Write the screenful of the file containing the tag named by the tagstring argument. 

See the dags utility. The tags feature represented by -t tagstring and the :t 
command is optional. It shall be provided on any system that also provides a 
conforming implementation of dags; otherwise, the use of -t produces undefined 
results. 

The file name resulting from the -t option shall be logically added as a prefix to the 
list of command line files, as if specified by the user. If the tag named by the 
tagstring argument is not found, it shall be an error, and more shall take no further 
action. 

If the tag specifies a line number, the first line of the display shall contain the 
beginning of that line. If the tag specifies a pattern, the first line of the display shall 
contain the beginning of the matching text from the first line of the file that 
contains that pattern. If the line does not exist in the file or matching text is not 
found, an informational message to this effect shall be displayed, and more shall 
display the default screen as if -t had not been specified. 

If both the -t tagstring and -p command options are given, the -t tagstring shall be 
processed first; that is, the file and starting line for the display shall be as specified 
by -t, and then the -p more command shall be executed. If the line (matching text) 
specified by the -t command does not exist (is not found), no -p more command 
shall be executed for this file at any time. 

-u Treat a <backspace> character as a printable control character, displayed as an 

implementation-dependent character sequence (see the EXTENDED 
DESCRIPTION section), suppressing backspacing and the special handling that 
produces underlined or standout mode text on some terminal types. Also, do not 
ignore a <carriage-return> character at the end of a line. 

OPERANDS 

The following operand shall be supported: 

file A path name of an input file. If no file operands are specified, the standard input 

shall be used. If a file is ' - ', the standard input shall be read at that point in the 
sequence. 

STDIN 

The standard input shall be used only if no file operands are specified, or if a file operand is ' . 
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25912 INPUT FILES 


25913 Notes to Reviewers 

25914 This section zvith side shading zvill not appear in the final copy. - Ed. 

25915 Dl, XCU, ERN 308 raises the issue of whether stderr is opened for input and output. There is 

25916 also a corresponding ERN against XSH. 

25917 The input files being examined shall be text files. If standard output is a terminal, standard error 

25918 shall be used to read commands from the user. If standard output is a terminal, standard error is 

25919 not readable, and command input is needed, more may attempt to obtain user commands from 

25920 the controlling terminal (for example, /dev/tty); otherwise, more shall terminate with an error 

25921 indicating that it was unable to read user commands. If standard output is not a terminal, no 

25922 error shall result if standard error cannot be opened for reading. 


25923 ENVIRONMENT VARIABLES 

25924 The following environment variables shall affect the execution of more: 

25925 COLUMNS Override the system-selected horizontal screen size. See the System Interface I 

25926 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for I 

25927 valid values and results when it is unset or null. 


25928 EDITOR Used by the v command to select an editor. See the EXTENDED DESCRIPTION 

25929 section. 


25930 

25931 

25932 

25933 

25934 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


25935 

25936 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


25937 

25938 

25939 


LCjCOLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi- I 
character collating elements within regular expressions. 


25940 

25941 

25942 

25943 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes within regular 
expressions. 


25944 LC_MESSAGES 

25945 Determine the locale that should be used to affect the format and contents of 

25946 diagnostic messages written to standard error and informative messages written to 

25947 standard output. 


25948 XSI 

25949 

25950 

25951 

25952 

25953 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

LINES Override the system-selected vertical screen size, used as the number of lines in a I 

screenful. See the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 8, Environment Variables for valid values and results when it is unset or I 
null. The -n option shall take precedence over the LINES variable for determining 
the number of lines in a screenful. 


25954 

25955 

25956 


MORE Determine a string containing options described in the OPTIONS section preceded 

with hyphens and <blank> character-separated as on the command line. Any I 
command line options shall be processed after those in the MORE variable, as if I 
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25957 the command line were: 

25958 more $MORE options operands 

25959 The MORE variable shall take precedence over the TERM and LINES variables for 

25960 determining the number of lines in a screenful. 

25961 TERM Determine the name of the terminal type. If this variable is unset or null, an 

25962 unspecified default terminal type is used. 

25963 ASYNCHRONOUS EVENTS 

25964 Default. 

25965 STDOUT 

25966 The standard output shall be used to write the contents of the input files. 

25967 STDERR 

25968 Used for diagnostic messages and user commands (see the INPUT FILES section), and, if 

25969 standard output is a terminal device, to write a prompting string. The prompting string shall I 

25970 shall appear on the screen line below the last line of the file displayed in the current screenful. I 

25971 The prompt shall contain the name of the file currently being examined and shall contain an I 

25972 end-of-file indication and the name of the next file, if any, when prompting at the end-of-file. If I 

25973 an error or informational message is displayed, it is unspecified whether it is contained in the I 

25974 prompt. If it is not contained in the prompt, it shall be displayed and then the user shall be I 

25975 prompted for a continuation character, at which point another message or the user prompt may I 

25976 be displayed. The prompt is otherwise unspecified. It is unspecified whether informational I 

25977 messages are written for other user commands. I 

25978 OUTPUT FILES 

25979 None. 

25980 EXTENDED DESCRIPTION 

25981 The following subsection describes the behavior of more when the standard output is a terminal I 

25982 device. If the standard output is not a terminal device, no options other than -s shall have any I 

25983 effect, and all input files shall be copied to standard output otherwise unmodified, at which time I 

25984 more shall exit without further action. I 

25985 The number of lines available per screen shall be determined by the -n option, if present, or by I 

25986 examining values in the environment (see the ENVIRONMENT VARIABLES section). If neither I 

25987 method yields a number, an unspecified number of lines shall be used. I 

25988 The maximum number of lines written shall be one less than this number, because the screen I 

25989 line after the last line written shall be used to write a user prompt and user input. If the number I 

25990 of lines in the screen is less than two, the results are undefined. It is unspecified whether user I 

25991 input is permitted to be longer than the remainder of the single line where the prompt has been I 

25992 written. I 

25993 The number of columns available per line shall be determined by examining values in the I 

25994 environment (see the ENVIRONMENT VARIABLES section), with a default value as described I 

25995 in System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment I 

25996 Variables. I 

25997 Lines that are longer than the display shall be folded; the length at which folding occurs is I 

25998 unspecified, but should be appropriate for the output device. Folding may occur between glyphs I 

25999 of single characters that take up multiple display columns. I 

26000 When standard output is a terminal and -u is not specified, more shall treat <backspace> I 

26001 characters and <carriage-return> characters specially: 
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26004 

26005 

26006 
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• A character, followed first by a sequence of n <backspace> characters (where n is the same as I 
the number of column positions that the character occupies), then by n underscore characters I 

shall cause that character to be written as underlined text, if the terminal type I 
supports that. The n underscore characters, followed first by n <backspace> characters, then I 
any character with n column positions, shall also cause that character to be written as I 
underlined text, if the terminal type supports that. I 

• A sequence of n <backspace> characters (where n is the same as the number of column I 
positions that the previous character occupies) that appears between two identical printable I 
characters shall cause the first of those two characters to be written as emboldened text (that I 
is, visually brighter, standout mode, or inverse-video mode), if the terminal type supports I 
that, and the second to be discarded. Immediately subsequent occurrences of I 
<backspace>/character pairs for that same character also shall be discarded. (For example, 
the sequence "a\ba\ba\ba" is interpreted as a single emboldened ' a'.) 

• The more utility shall logically discard all other <backspace> characters from the line as well I 

as the character which precedes them, if any. I 

• A <carriage-return> character at the end of a line shall be ignored, rather than being written I 

as a non-printable character, as described in the next paragraph. I 

It is implementation-dependent how other non-printable characters are written. 
Implementations should use the same format that they use for the ex print command; see the I 
OPTIONS section within the ed utility. It is unspecified whether a multi-column character shall I 
be separated if it crosses a logical line boundary; it shall not be discarded. The behavior is I 
unspecified if the number of columns on the display is less than the number of columns any I 
single character in the line being displayed would occupy. I 

When each new file is displayed (or redisplayed), more shall write the first screen of the file. I 
Once the initial screen has been written, more shall prompt for a user command. If the execution I 
of the user command results in a screen that has lines in common with the current screen, and I 
the device has sufficient terminal capabilities, more shall scroll the screen; otherwise, it is I 
unspecified whether the screen is scrolled or redrawn. I 

For all files but the last (including standard input if no file was specified, and for the last file as I 
well, if the -e option was not specified), when more has written the last line in the file, more shall I 
prompt for a user command. This prompt shall contain the name of the next file as well as an I 
indication that more has reached end-of-file. If the user command is f, <control>-F, <space>, j, I 
<newline>, d, <control>-D, or s, more shall display the next file. Otherwise, if displaying the last I 
file, more shall exit. Otherwise, more shall execute the user command specified. I 

Several of the commands described in this section display a previous screen from the input I 
stream. In the case that text is being taken from a non-rewindable stream, such as a pipe, it is I 
implementation-dependent how much backwards motion is supported. If a command cannot be I 
executed because of a limitation on backwards motion, an error message to this effect shall be I 
displayed, the current screen shall not change, and the user shall be prompted for another I 
command. I 

If a command cannot be performed because there are insufficient lines to display, more shall alert I 
the terminal. If a command cannot be performed because there are insufficient lines to display or I 
a / command fails: if the input is the standard input, the last screen in the file may be displayed; I 
otherwise, the current file and screen shall not change, and the user shall be prompted for I 
another command. I 

The interactive commands in the following sections shall be supported. Some commands can be 
preceded by a decimal integer, called count in the following descriptions. If not specified with 
the command, count shall default to 1. In the following descriptions, pattern is a basic regular I 
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expression, as described in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 9.3, Basic Regular Expressions. The term "examine” is historical usage meaning "open I 
the file for viewing”; for example, more foo would be expressed as examining file foo. In the I 
following descriptions, unless otherwise specified, line is a logical line in the more display, not a I 
line from the file being examined. I 

In the following descriptions, the current position refers to two things: I 

1. The position of the current line on the screen I 

2. The line number (in the file) of the current line on the screen I 

Usually, the line on the screen corresponding to the current position is the third line on the I 
screen. If this is not possible (there are fewer than three lines to display or this is the first page of I 
the file, or it is the last page of the file), then the current position is either the first or last line on I 
the screen as described later. I 

Help 

Synopsis: h 

Write a summary of these commands and other implementation-dependent commands. The I 
behavior shall be as if the more utility were executed with the -e option on a file that contained I 
the summary information. The user shall be prompted as described earlier in this section when I 
end-of-file is reached. If the user command is one of those specified to continue to the next file, I 
more shall return to the file and screen state from which the h command was executed. I 

Scroll Forward One Screenful I 

Synopsis: [count] f I 

[count] <control>-F 

Scroll forward count lines, with a default of one screenful. If count is more than the screen size, I 
only the final screenful shall be written. I 

Scroll Backward One Screenful I 

Synopsis: [count] b I 

[count] <control>-B 

Scroll backward count lines, with a default of one screenful (see the -n option). If count is more I 
than the screen size, only the final screenful shall be written. 

Scroll Forward One Line 

Synopsis: [count] <space> 

[count] j 

[count] <newline> 

Scroll forward count lines. The default count for the <space> character shall be one screenful; for j 
and <newline> character, one line. The entire count lines shall be written, even if count is more I 
than the screen size. I 
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Scroll Backward One Line 

Synopsis: [count] k 

Scroll backward count lines. The entire count lines shall be written, even if count is more than the I 
screen size. 

Scroll Forward One Half Screenful 

Synopsis: [count] d 

[count] <control>-D 

Scroll forward count lines, with a default of one half of the screen size. If count is specified, it 
shall become the new default for subsequent d, <control>-D, and u commands. I 

Skip Forward One Line 

Synopsis: [count] s 

Display the screenful beginning with the line count lines after the last line on the current screen. I 
If count would cause the current position to be such that less than one screenful would be I 
written, the last screenful in the file shall be written. 

Scroll Backward One Half Screenful 

Synopsis: [count] u 

[count] <control>-U 

Scroll backward count lines, with a default of one half of the screen size. If count is specified, it 
shall become the new default for subsequent d, <control>-D, u, and <control>-U commands. I 
The entire count lines shall be written, even if count is more than the screen size. I 

Go to Beginning of File 

Synopsis: [count] g 

Display the screenful beginning with line count. I 

Go to End-of-File 

Synopsis: [count] G 

If count is specified, display the screenful beginning with the line count. Otherwise, display the I 
last screenful of the file. I 

Refresh the Screen 

Synopsis: r 

<control>-L 

Refresh the screen. 
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Discard and Refresh 

Synopsis: R 

Refresh the screen, discarding any buffered input. If the current file is non-seekable, buffered 
input shall not be discarded and the R command is equivalent to the r command. 

Mark Position 

Synopsis: mletter 

Mark the current position with the letter named by letter, where letter represents the name of one 
of the lowercase letters of the portable character set. When a new file is examined, all marks may 
be lost. 

Return to Mark 

Synopsis: 'letter 

Return to the position that was previously marked with the letter named by letter, making that 
line the current position. 

Return to Previous Position 

Synopsis: '' 

Return to the position from which the last large movement command was executed (where a 
“large movement" is defined as any movement of more than a screenful of lines). If no such I 
movements have been made, return to the beginning of the file. I 

Search Forward for Pattern 

Synopsis: [count] / [ ! ]pattern<newline> 

Display the screenful beginning with the count th line containing the pattern. The search shall I 
start after the first line currently displayed. The null regular expression (' /' followed by a I 
<newline> character) shall repeat the search using the previous regular expression, with a I 
default count. If the character ' !' is included, the matching lines shall be those that do not I 
contain the pattern. If no match is found for the pattern, a message to that effect shall be I 
displayed. I 

Search Backward for Pattern 

Synopsis: [count] ? [ ! ]pattern<newline> 

Display the screenful beginning with the conntth previous line containing the pattern. The I 
search shall start on the last line before the first line currently displayed. The null regular I 
expression (' ?' followed by a <newline> character) shall repeat the search using the previous I 
regular expression, with a default count. If the character ' !' is included, matching lines shall be I 
those that do not contain the pattern. I 

If no match is found for the pattern, a message to that effect shall be displayed. I 
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Repeat Search 

Synopsis: [count] n 

Repeat the previous search for countth line containing the last pattern (or not containing the last I 
pattern, if the previous search was " / ! " or " ? ! "). 

Repeat Search in Reverse 

Synopsis: [count] N 

Repeat the search in the opposite direction of the previous search for the countth line containing I 
the last pattern (or not containing the last pattern, if the previous search was " / ! " or " ? ! "). I 

Examine New File 

Synopsis: :e [filename] <newline> 

Examine a new file. If the filename argument is not specified, the current file (see the :n and :p I 
commands below) shall be re-examined. The filename shall be subjected to the process of shell I 
word expansions (see Section 2.6 on page 49); if more than a single path name results, the effects 
are unspecified. If filename is a number sign (' #'), the previously examined file shall be re- I 
examined. It filename is not accessible for any reason (including that it is a non-seekable file), an I 
error message to this effect shall be displayed and the current file and screen shall not change. I 

Examine Next File 

Synopsis: [count]: n 

Examine the next file. If a number count is specified, the count th next file shall be examined. If 
filename refers to a non-seekable file, the results are unspecified. 

Examine Previous File 

Synopsis: [count] :p 

Examine the previous file. If a number count is specified, the count th previous file shall be 
examined. It filename refers to a non-seekable file, the results are unspecified. 

Go to Tag 

Synopsis: :t tagstring<newline> 

If the file containing the tag named by the tagstring argument is not the current file, examine the I 
file, as if the :e command was executed with that file as the argument. Otherwise, or in addition, I 
display the screenful beginning with the tag, as described for the -t option (see the OPTIONS I 
section). If the dags utility is not supported by the system, the use of :t produces undefined I 
results. 

Invoke Editor 

Synopsis: v 

Invoke an editor to edit the current file being examined. If standard input is being examined, the 
results are unspecified. The name of the editor shall be taken from the environment variable 
EDITOR, or shall default to vi. If the last path name component in EDITOR is either vi or ex, the I 
editor shall be invoked with a - linenumber command line argument, where linenumber is the line I 
number of the physical line containing the logical line currently displayed as the first line of the I 
screen. It is implementation-dependent whether line-setting options are passed to editors other I 


Commands and Utilities, Issue 6 


685 



more 


Utilities 


26190 

26191 

26192 

26193 

26194 

26195 

26196 

26197 

26198 

26199 

26200 
26201 

26202 

26203 

26204 

26205 

26206 

26207 

26208 

26209 

26210 

26211 

26212 

26213 

26214 

26215 

26216 

26217 

26218 

26219 

26220 
26221 
26222 

26223 

26224 

26225 

26226 

26227 

26228 

26229 

26230 

26231 


than vi and ex. I 

When the editor exits, more shall resume with the same file and screen as when the editor was I 
invoked. I 

Display Position 

Synopsis : 

<control>-G 

Write a message for which the information references the first byte of the line after the last line of I 
the file on the screen. This message shall include the name of the file currently being examined, I 
its number relative to the total number of files there are to examine, the physical line number, I 
the byte number and the total bytes in the file, and what percentage of the file precedes the I 
current position. If more is reading from standard input, or the file is shorter than a single screen, I 
the line number, the byte number, the total bytes, and the percentage need not be written. I 

Quit 

Synopsis : q 

= q 

zz 

Exit more. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If an error is encountered accessing a file when using the :n command, more shall attempt to 
examine the next file in the argument list, but the final exit status shall be affected. If an error is 
encountered accessing a file via the :p command, more shall attempt to examine the previous file 
in the argument list, but the final exit status shall be affected. If an error is encountered accessing 
a file via the :e command, more shall remain in the current file and the final exit status shall not 
be affected. 

APPLICATION USAGE 

When the standard output is not a terminal, only the -s filter-modification option is effective. I 
This is based on historical practice. For example, a typical implementation of man pipes its I 
output through more -s to squeeze excess white space for terminal users. When man is piped to 
Ip, however, it is undesirable for this squeezing to happen. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

The -p allows arbitrary commands to be executed at the start of each file. Examples are: 
more -p Gfilet file2 

Examine each file starting with its last screenful. 
more- p 100 fit el file! 

Examine each file starting with line 100 in the current position (usually the third line, so line 
98 would be the first line written). 
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more -p /100filel file! 

Examine each file starting with the first line containing the string "100" in the current 
position 

RATIONALE 

The more utility, available in BSD and BSD-derived systems, was chosen as the prototype for the 
POSIX file display program since it is more widely available than either the public-domain 
program less or than pg, a pager provided in System V. The 4.4 BSD more is the model for the 
features selected; it is almost fully upward-compatible from the 4.3 BSD version in wide use and 
has become more amenable for vi users. Several features originally derived from various file 
editors, found in both less and pg, have been added to this volume of IEEE Std. 1003.1-200x as 
they have proved extremely popular with users. 

There are inconsistencies between more and vi that result from historical practice. For example, 
the single-character commands h, f, b, and <space> are screen movers in more, but cursor 
movers in vi. These inconsistencies were maintained because the cursor movements are not 
applicable to more and the powerful functionality achieved without the use of the control key 
justifies the differences. 

The tags interface has been included in a program that is not a text editor because it promotes 
another degree of consistent operation with vi. It is conceivable that the paging environment of 
more would be superior for browsing source code files in some circumstances. 

The operating mode referred to for block-mode terminals effectively adds a <newline> to each I 
Synopsis line that currently has none. So, for example, d<newline> would page one screenful. I 
The mode could be triggered by a command line option, environment variable, or some other I 
method. The details are not imposed by this volume of IEEE Std. 1003.1-200x because there are I 
so few systems known to support such terminals. Nevertheless, it was considered that all I 
systems should be able to support more given the exception cited for this small community of I 
terminals because, in comparison to vi, the cursor movements are few and the command set 
relatively amenable to the optional <newline>s. 

Some versions of more provide a shell escaping mechanism similar to the ex ! command. The 
standard developers did not consider that this was necessary in a paginator, particularly given 
the wide acceptance of multiple window terminals and job control features. (They chose to 
retain such features in the editors and mailx because the shell interaction also gives an 
opportunity to modify the editing buffer, which is not applicable to more). 

The -p (position) option replaces the + command because of the Utility Syntax Guidelines. In I 
early proposals, it took a pattern argument, but historical less provided the more general facility of I 
a command. It would have been desirable to use the same -c as ex and vi, but the letter was I 
already in use. 

The text stating "from a non-rewindable stream ... implementations may limit the amount of 
backwards motion supported" would allow an implementation that permitted no backwards 
motion beyond text already on the screen. It was not possible to require a minimum amount of 
backwards motion that would be effective for all conceivable device types. The implementation 
should allow the user to back up as far as possible, within device and reasonable memory 
allocation constraints. I 

Historically, non-printable characters were displayed using the ARPA standard mappings, I 
which are as follows: I 

1. Printable characters are left alone. I 

2. Control characters less than \177 are represented as followed by the character offset from I 

the ' @' character in the ASCII map; for example, \007 is represented as ' G'. I 
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26279 3. \ 177 is represented as followed by' ?'. I 

26280 The display of characters having their eighth bit set was less standard. Existing implementations I 

26281 use hex (0x00), octal (\000), and a meta-bit display. (The latter displayed characters with their I 

26282 eighth bit set as the two characters "M-, " followed by the seven bit display as described I 

26283 previously.) The latter probably has the best claim to historical practice because it was used with I 

26284 the -v option of 4 BSD and 4 BSD-derived versions of the cat utility since 1980. I 

26285 No specific display format is required by IEEE Std. 1003.1-200x. Implementations are I 

26286 encouraged to conform to historic practice in the absence of any strong reason to diverge. I 

26287 FUTURE DIRECTIONS 

26288 None. I 

26289 SEE ALSO I 

26290 ctags, ed, ex, vi I 

26291 CHANGE HISTORY 

26292 First released in Issue 4. 

26293 Issue 5 

26294 FUTURE DIRECTIONS section added. 

26295 Issue 6 

26296 This utility is now marked as part of the User Portability Utilities option. 

26297 The obsolescent SYNOPSIS is removed. I 

26298 The utility has been extensively reworked for alignment with the IEEE P1003.2b draft standard: I 

26299 • Changes have been made as result of PASC Interpretations 1003.2-92 #37 and 109. I 

26300 • The more utility should be able to handle underlined and emboldened displays of characters I 

26301 that are wider than a single column position. I 
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26302 NAME 

26303 mv — move files 


26304 SYNOPSIS 

26305 mv [—fi] source_file target_file 


26306 mv [—f i ] source_fHe . . . target_file 


26307 DESCRIPTION 

26308 In the first synopsis form, the mv utility shall move the file named by the source_file operand to 

26309 the destination specified by the target_Jile. This first synopsis form is assumed when the final 

26310 operand does not name an existing directory and is not a symbolic link referring to an existing I 

26311 directory. I 

26312 In the second synopsis form, mv shall move each file named by a sourceJile operand to a 

26313 destination file in the existing directory named by the target_dir operand, or referenced if I 

26314 target_dir is a symbolic link referring to an existing directory. The destination path for each I 

26315 sonrce_file shall be the concatenation of the target directory, a single slash character, and the last 

26316 path name component of the sourcejile. This second form is assumed when the final operand 

26317 names an existing directory. 

26318 If any operand specifies an existing file of a type not specified by the System Interfaces volume 

26319 of IEEE Std. 1003.1-200x, the behavior is implementation-dependent. 

26320 For each sonrce_file the following steps shall be taken: 

26321 1. If the destination path exists, the -f option is not specified, and either of the following 

26322 conditions is true: 


26323 a. The permissions of the destination path do not permit writing and the standard input 

26324 is a terminal. 


26325 


b. The -i option is specified. 


26326 

26327 

26328 


The mv utility shall write a prompt to standard error and read a line from standard input. If 
the response is not affirmative, mv shall do nothing more with the current source_file and 
go on to any remaining source Jile s. 


26329 2. The mv utility shall perform actions equivalent to the rename() function defined in the 

26330 System Interfaces volume of IEEE Std. 1003.1-200x, called with the following arguments: 


26331 


a. The sourceJile operand is used as the old argument. 


26332 


b. The destination path is used as the new argument. 


26333 

26334 

26335 

26336 

26337 


If this succeeds, mv shall do nothing more with the current source_file and go on to any 
remaining sourceJile s. If this fails for any reasons other than those described for the err no 
[EXDEV] in the System Interfaces volume of IEEE Std. 1003.1-200x, mv shall write a 
diagnostic message to standard error, do nothing more with the current source Jile, and go 
on to any remaining source_files. 


26338 

26339 

26340 

26341 


3. If the destination path exists, and it is a file of type directory and s ource_file is not a file of 
type directory, or it is a file not of type directory and sourcejile is a file of type directory, 
mv shall write a diagnostic message to standard error, do nothing more with the current 
source_file, and go on to any remaining source_files. 


26342 

26343 

26344 


4. If the destination path exists, mv shall attempt to remove it. If this fails for any reason, mv 
shall write a diagnostic message to standard error, do nothing more with the current 
source Jile , and go on to any remaining source Jiles. 
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26345 

26346 

26347 

26348 

26349 

26350 

26351 

26352 

26353 

26354 

26355 

26356 

26357 

26358 

26359 

26360 

26361 

26362 

26363 

26364 

26365 

26366 

26367 

26368 

26369 

26370 

26371 

26372 

26373 

26374 

26375 

26376 

26377 

26378 

26379 

26380 

26381 

26382 

26383 

26384 


5. The file hierarchy rooted in source_fiie shall be duplicated as a file hierarchy rooted in the I 

destination path. If sonrce_file or any of the files below it in the hierarchy are symbolic links, I 
the links themselves shall be duplicated, including their contents, rather than any files to I 
which they refer. The following characteristics of each file in the file hierarchy shall be I 
duplicated: I 

• The time of last data modification and time of last access 

• The user ID and group ID 

• The file mode 

If the user ID, group ID, or file mode of a regular file cannot be duplicated, the file mode 
bits S_ISUID and S_ISGID shall not be duplicated. 

When files are duplicated to another file system, the implementation may require that the 
process invoking mv has read access to each file being duplicated. 

If the duplication of the file hierarchy fails for any reason, mv shall write a diagnostic 
message to standard error, do nothing more with the current sourceJile, and go on to any 
remaining source_file s. 

If the duplication of the file characteristics fails for any reason, mv shall write a diagnostic 
message to standard error, but this failure shall not cause mv to modify its exit status. 

6. The file hierarchy rooted in source_file shall be removed. If this fails for any reason, mv shall 
write a diagnostic message to the standard error, do nothing more with the current 
source_file, and go on to any remaining source_files. 

OPTIONS 

The mv utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-f Do not prompt for confirmation if the destination path exists. Any previous 

occurrences of the -i option is ignored. 

-i Prompt for confirmation if the destination path exists. Any previous occurrences of 

the -f option is ignored. 

Specifying more than one of the -f or -i options shall not be considered an error. The last option 
specified shall determine the behavior of mv. 

OPERANDS 

The following operands shall be supported: 

sourcejile A path name of a file or directory to be moved. 

targetjile A new path name for the file or directory being moved. 

target_dir A path name of an existing directory into which to move the input files. 

STDIN 

Used to read an input line in response to each prompt specified in the STDERR section. 
Otherwise, the standard input shall not be used. 

INPUT FILES 

The input files specified by each source_file operand can be of any file type. 
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26385 

26386 

26387 

26388 

26389 

26390 

26391 

26392 

26393 

26394 

26395 

26396 

26397 

26398 

26399 

26400 

26401 

26402 

26403 

26404 

26405 

26406 

26407 

26408 

26409 

26410 

26411 

26412 

26413 

26414 

26415 

26416 

26417 

26418 

26419 

26420 

26421 

26422 

26423 

26424 

26425 

26426 

26427 

26428 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of mv: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LCJZOLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements used in the extended regular expression defined for 
the yesexpr locale keyword in the LC_MESSAGES category. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the behavior of character classes used in the extended 
regular expression defined for the yesexpr locale keyword in the LC_MESSAGES 
category. 

LC_MESSAGES 

Determine the locale for the processing of affirmative responses that should be 
used to affect the format and contents of diagnostic messages written to standard 
error. 


xsi NLSPATEt Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Prompts shall be written to the standard error under the conditions specified in the 
DESCRIPTION section. The prompts shall contain the destination path name, but their format is 
otherwise unspecified. Otherwise, the standard error shall be used only for diagnostic messages. 

OUTPUT FILES 

The output files may be of any file type. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 All input files were moved successfully. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If the copying or removal of source_file is prematurely terminated by a signal or error, mv may 
leave a partial copy of source_file at the source or destination. The mv utility shall not modify 
both sourceJile and the destination path simultaneously; termination at any point shall leave 
either source_file or the destination path complete. 
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26429 APPLICATION USAGE 

26430 None. 

26431 EXAMPLES 

26432 If the current directory contains only files a (of any type defined by the System Interfaces 

26433 volume of IEEE Std. 1003.1-200x), b (also of any type), and a directory c: 

26434 mv a b c 

26435 mv c d 

26436 results with the original files a and b residing in the directory d in the current directory. 

26437 RATIONALE 

26438 Early proposals diverged from the SVID and BSD historical practice in that they required that 

26439 when the destination path exists, the -f option is not specified, and input is not a terminal, mv 

26440 fails. This was done for compatibility with cp. The current text returns to historical practice. It 

26441 should be noted that this is consistent with the rename ( ) function defined in the System 

26442 Interfaces volume of IEEE Std. 1003.1-200x, which does not require write permission on the 

26443 target. 

26444 For absolute clarity, paragraph (1), describing the behavior of mv when prompting for 

26445 confirmation, should be interpreted in the following manner: 

26446 if (exists AND (NOT f_option) AND 

26447 ( (not_writable AND input_is_terminal) OR i_option) ) 

26448 The -i option exists on BSD systems, giving applications and users a way to avoid accidentally 

26449 unlinking files when moving others. When the standard input is not a terminal, the 4.3 BSD mv 

26450 deletes all existing destination paths without prompting, even when -i is specified; this is 

26451 inconsistent with the behavior of the 4.3 BSD cp utility, which always generates an error when 

26452 the file is unwritable and the standard input is not a terminal. The standard developers decided 

26453 that use of -i is a request for interaction, so when the destination path exists, the utility takes 

26454 instructions from whatever responds to standard input. 

26455 The rename( ) function is able to move directories within the same file system. Some historical 

26456 versions of mv have been able to move directories, but not to a different file system. The 

26457 standard developers considered that this was an annoying inconsistency, so this volume of 

26458 IEEE Std. 1003.1-200x requires directories to be able to be moved even across file systems. There 

26459 is no -R option to confirm that moving a directory is actually intended, since such an option was 

26460 not required for moving directories in historical practice. Requiring the application to specify it 

26461 sometimes, depending on the destination, seemed just as inconsistent. The semantics of the 

26462 rename () function were preserved as much as possible. For example, mv is not permitted to 

26463 "rename" files to or from directories, even though they might be empty and removable. 

26464 Historic implementations of mv did not exit with a non-zero exit status if they were unable to 

26465 duplicate any file characteristics when moving a file across file systems, nor did they write a 

26466 diagnostic message for the user. The former behavior has been preserved to prevent scripts from 

26467 breaking; a diagnostic message is now required, however, so that users are alerted that the file 

26468 characteristics have changed. 

26469 The exact format of the interactive prompts is unspecified. Only the general nature of the 

26470 contents of prompts are specified because implementations may desire more descriptive 

26471 prompts than those used on historical implementations. Therefore, an application not using the 

26472 -f option or using the -i option relies on the system to provide the most suitable dialog directly 

26473 with the user, based on the behavior specified. I 

26474 When mv is dealing with a single file system and source_file is a symbolic link, the link itself is I 

26475 moved as a consequence of the dependence on the rename( ) functionality, per the I 
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26476 DESCRIPTION. Across file systems, this has to be made explicit. I 

26477 FUTURE DIRECTIONS 

26478 None. 

26479 SEE ALSO 

26480 cp, In 

26481 CHANGE HISTORY 

26482 First released in Issue 2. 

26483 Issue 4 

26484 Aligned with the ISO/IEC 9945-2:1993 standard. I 

26485 Issue 6 I 

26486 The mv utility is changed to describe processing of symbolic links as specified in the I 

26487 IEEE P1003.2b draft standard. I 
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26488 NAME 

26489 newgrp — change to a new group 

26490 SYNOPSIS 

26491 UP newgrp [—1] [group 

26492 

26493 DESCRIPTION 

26494 The newgrp utility shall create a new shell execution environment with a new real and effective 

26495 group identification. Of the attributes listed in Section 2.12 on page 90, the new shell execution 

26496 environment shall retain the working directory, file creation mask, and exported variables from 

26497 the previous environment (that is, open files, traps, unexported variables, alias definitions, shell 

26498 functions, and set options may be lost). All other aspects of the process environment that are 

26499 preserved by the exec family of functions defined in the System Interfaces volume of 

26500 IEEE Std. 1003.1-200x shall also be preserved by newgrp-, whether other aspects are preserved is 

26501 unspecified. 

26502 A failure to assign the new group identifications (for example, for security or password-related 

26503 reasons) shall not prevent the new shell execution environment from being created. 

26504 The newgrp utility shall affect the supplemental groups for the process as follows: 

26505 • On systems where the effective group ID is normally in the supplementary group list (or 

26506 whenever the old effective group ID actually is in the supplementary group list): 

26507 — If the new effective group ID is also in the supplementary group list, newgrp shall change 

26508 the effective group ID. 

26509 — If the new effective group ID is not in the supplementary group list, newgrp shall add the 

26510 new effective group ID to the list, if there is room to add it. 

26511 • On systems where the effective group ID is not normally in the supplementary group list (or 

26512 whenever the old effective group ID is not in the supplementary group list): 

26513 — If the new effective group ID is in the supplementary group list, newgrp shall delete it. 

26514 — If the old effective group ID is not in the supplementary list, newgrp shall add it if there is 

26515 room. 

26516 Note: The System Interfaces volume of IEEE Std. 1003.1-200x does not specify whether the 

26517 effective group ID of a process is included in its supplementary group list. 

26518 With no operands, newgrp shall change the effective group back to the groups identified in the 

26519 useds user entry, and shall set the list of supplementary groups to that set in the useds group 

26520 database entries. 

26521 If a password is required for the specified group, and the user is not listed as a member of that 

26522 group in the group database, the user shall be prompted to enter the correct password for that 

26523 group. If the user is listed as a member of that group, no password is requested. If no password 

26524 is required for the specified group, it is implementation-dependent whether users not listed as 

26525 members of that group can change to that group. Whether or not a password is required, 

26526 implementation-dependent system accounting or security mechanisms may impose additional 

26527 authorization restrictions that may cause newgrp to write a diagnostic message and suppress the 

26528 changing of the group identification. 

26529 OPTIONS 

26530 The newgrp utility shall conform to the System Interface Definitions volume of I 

26531 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 
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26532 The following option shall be supported: 

26533 -1 (The letter ell.) Change the environment to what would be expected if the user 

26534 actually logged in again. 


26535 OPERANDS 

26536 The following operand shall be supported: 


A group name from the group database or a non-negative numeric group ID. 
Specifies the group ID to which the real and effective group IDs shall be set. If 
group is a non-negative numeric string and exists in the group database as a group 
name (see getgrnam()), the numeric group ID associated with that group name 
shall be used as the group ID. 

26542 STDIN 

26543 Not used. 


26537 group 

26538 

26539 

26540 

26541 


26544 INPUT FILES 

26545 The file /dev/tty shall be used to read a single line of text for password checking, when one is 

26546 required. 


26547 ENVIRONMENT VARIABLES 

26548 The following environment variables shall affect the execution of newgrp : 


26549 

26550 

26551 

26552 

26553 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


26554 

26555 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


26556 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

26557 characters (for example, single-byte as opposed to multi-byte characters in 

26558 arguments). 

26559 LC_MESSAGES 

26560 Determine the locale that should be used to affect the format and contents of 

26561 diagnostic messages written to standard error. 

26562 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

26563 ASYNCHRONOUS EVENTS 

26564 Default. 


26565 STDOUT 

26566 Not used. 


26567 STDERR 

26568 Used for diagnostic messages and a prompt string for a password, if one is required. Diagnostic 

26569 messages may be written in cases where the exit status is not available. See the EXIT STATUS 

26570 section. 


26571 OUTPUT FILES 

26572 None. 
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26573 EXTENDED DESCRIPTION 

26574 None. 

26575 EXIT STATUS 

26576 If neivgrp succeeds in creating a new shell execution environment, whether or not the group 

26577 identification was changed successfully, the exit status shall be the exit status of the shell. 

26578 Otherwise, the following exit value shall be returned: 

26579 >0 An error occurred. 

26580 CONSEQUENCES OF ERRORS 

26581 The invoking shell may terminate. 

26582 APPLICATION USAGE 

26583 There is no convenient way to enter a password into the Group Database. Use of group 

26584 passwords is not encouraged, because by their very nature they encourage poor security 

26585 practices. Group passwords may disappear in the future. 

26586 A common implementation of neivgrp is that the current shell uses exec to overlay itself with 

26587 neivgrp, which in turn overlays itself with a new shell after changing group. On some systems, 

26588 however, this may not occur and neivgrp may be invoked as a subprocess. 

26589 The neivgrp command is intended only for use from an interactive terminal. It does not offer a 

26590 useful interface for the support of applications. 

26591 The exit status of neivgrp is generally inapplicable. If neivgrp is used in a script, in most cases it 

26592 successfully invokes a new shell and the rest of the original shell script is bypassed when the 

26593 new shell exits. Used interactively, neivgrp displays diagnostic messages to indicate problems. 

26594 But usage such as: 

26595 newgrp foo 

26596 echo $? 

26597 is not useful because the new shell might not have access to any status neivgrp may have 

26598 generated (and most historical systems do not provide this status). A zero status echoed here 

26599 does not necessarily indicate that the user has changed to the new group successfully. Following 

26600 neivgrp with the id command provides a portable means of determining whether the group 

26601 change was successful or not. 

26602 Application writers should note that this utility need not be provided on systems that do not 

26603 support the User Portability Utilities option. 

26604 EXAMPLES 

26605 None. 

26606 RATIONALE 

26607 Most historical implementations use one of the exec functions to implement the behavior of 

26608 neivgrp. Errors detected before the exec leave the environment unchanged, while errors detected 

26609 after the exec leave the user in a changed environment. While it would be useful to have neivgrp 

26610 issue a diagnostic message to tell the user that the environment changed, it would be 

26611 inappropriate to require this change to some historical implementations. 

26612 The password mechanism is allowed in the group database, but how this would be 

26613 implemented is not specified. 

26614 The neivgrp utility was retained in this volume of IEEE Std. 1003.1-200x, even given the existence 

26615 of the multiple group permissions feature in the System Interfaces volume of 

26616 IEEE Std. 1003.1-200x, for several reasons. First, in some systems, the group ownership of a 

26617 newly created file is determined by the group of the directory in which the file is created, as 
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26618 allowed by the System Interfaces volume of IEEE Std. 1003.1-200x; on other systems, the group 

26619 ownership of a newly created file is determined by the effective group ID. On systems of the 

26620 latter type, newgrp allows files to be created with a specific group ownership. Finally, many 

26621 systems use the real group ID in accounting, and on such systems, newgrp allows the accounting 

26622 identity of the user to be changed. 

26623 FUTURE DIRECTIONS 

26624 None. 

26625 SEE ALSO 

26626 sh, the System Interfaces volume of IEEE Std. 1003.1-200x, exec 

26627 CHANGE HISTORY 

26628 First released in Issue 2. 

26629 Issue 4 

26630 Aligned with the ISO/IEC 9945-2:1993 standard. 

26631 The newgrp utility is now mandatory; it is optional in Issue 3. 

26632 Issue 6 

26633 This utility is now marked as part of the User Portability Utilities option. 

26634 The obsolescent SYNOPSIS is removed. 

26635 The text describing supplemental groups is no longer conditional on |NGROUPS_MAX} being 

26636 greater than 1. This is because |NGROUPS_MAX} now has a minimum value of 8. This is a FIPS 

26637 requirement. 
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26638 

26639 

26640 

26641 

26642 

26643 

26644 

26645 

26646 

26647 

26648 

26649 

26650 

26651 

26652 

26653 

26654 

26655 

26656 

26657 

26658 

26659 

26660 
26661 
26662 

26663 

26664 

26665 

26666 

26667 

26668 

26669 

26670 

26671 

26672 

26673 

26674 

26675 

26676 

26677 

26678 

26679 

26680 
26681 
26682 


NAME 

nice — invoke a utility with an altered nice value 

SYNOPSIS 

UP nice [—n increment ] utility [argument...] 

DESCRIPTION 

The nice utility shall invoke a utility, requesting that it be run with a different nice value (see the I 
System Interface Definitions volume of IEEE Std. 1003d-200x, Section 3.245, Nice Value). With I 
no options and only if the user has appropriate privileges, the executed utility shall be run with a I 
nice value that is some implementation-dependent quantity less than or equal to the nice value 
of the current process. If the user lacks appropriate privileges to affect the nice value in the 
requested manner, the nice utility shall not affect the nice value; in this case, a warning message 
may be written to standard error, but this shall not prevent the invocation of utility or affect the 
exit status. 

OPTIONS 

The nice utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following option is supported: 

-n increment Specify how the nice value of the executed utility shall be adjusted. The increment 
option-argument shall be a positive or negative decimal integer that shall be used 
to modify the nice value of the executed utility in an implementation-dependent 
manner. 

Positive increment values shall cause a lower or unchanged nice value. Negative 
increment values may require appropriate privileges and shall cause a higher or 
unchanged nice value. 

The nice value shall be bounded in an implementation-dependent manner. If the 
requested increment would raise or lower the nice value of the executed utility 
beyond implementation-dependent limits, then the limit whose value was 
exceeded shall be used. 


OPERANDS 

The following operands shall be supported: 

utility The name of a utility that is to be invoked. If the utility operand names any of the 

special built-in utilities in Section 2.14 on page 96, the results are undefined. 

argument Any string to be supplied as an argument when invoking the utility named by the 
utility operand. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of nice: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
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26683 


been defined. 


26684 

26685 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


26686 

26687 

26688 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


26689 LC_MESSAGES 

26690 Determine the locale that should be used to affect the format and contents of 

26691 diagnostic messages written to standard error. 

26692 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

26693 PATH Determine the search path used to locate the utility to be invoked. See the System I 

26694 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment I 

26695 Variables. I 


26696 ASYNCHRONOUS EVENTS 

26697 Default. 


26698 STDOUT 

26699 Not used. 


26700 STDERR 

26701 Used only for diagnostic messages. 

26702 OUTPUT FILES 

26703 None. 


26704 EXTENDED DESCRIPTION 

26705 None. 


26706 EXIT STATUS 

26707 If the utility utility is invoked, the exit status of nice shall be the exit status of utility; otherwise, 

26708 the nice utility shall exit with one of the following values: 

26709 1-125 An error occurred in the nice utility. 

26710 126 The utility specified by utility was found but could not be invoked. 

26711 127 The utility specified by utility could not be found. 

26712 CONSEQUENCES OF ERRORS 

26713 Default. 

26714 APPLICATION USAGE 

26715 The only guaranteed portable uses of this utility are: 

26716 nice utility 

26717 Run utility with the default lower nice value. 

26718 nice -n <positive integer> utility 

26719 Run utility with a lower nice value. 

26720 On some systems they have no discernible effect on the invoked utility and on some others they 

26721 are exactly equivalent. 

26722 Historical systems have frequently supported the <positive integer> up to 20. Since there is no 

26723 error penalty associated with guessing a number that is too high, users without access to the 

26724 system conformance document (to see what limits are actually in place) could use the historical 

26725 1 to 20 range or attempt to use very large numbers if the job should be truly low priority. 
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26726 

26727 

26728 

26729 

26730 

26731 

26732 

26733 

26734 

26735 

26736 

26737 

26738 

26739 

26740 

26741 

26742 

26743 

26744 

26745 

26746 

26747 

26748 

26749 

26750 

26751 

26752 

26753 

26754 

26755 

26756 

26757 

26758 

26759 

26760 

26761 

26762 

26763 

26764 

26765 

26766 

26767 

26768 

26769 

26770 

26771 


The nice value value of a process can be displayed using the command: 

ps —o nice 

The command, env, nice, nohup, time, and xargs utilities have been specified to use exit code 127 if 
an error occurs so that applications can distinguish "failure to find a utility" from "invoked 
utility exited with an error indication". The value 127 was chosen because it is not commonly 
used for other meanings; most utilities use small values for "normal error conditions" and the 
values above 128 can be confused with termination due to receipt of a signal. The value 126 was 
chosen in a similar manner to indicate that the utility could be found, but not invoked. Some 
scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction 
between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 
exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 
any other reason. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

Due to the text about the limits of the nice value being implementation-dependent, nice is not 
actually required to change the nice value of the executed command; the limits could be zero 
differences from the system default, although the implementor is required to document this fact 
in the conformance document. 

The 4.3 BSD version of nice does not check if increment is a valid decimal integer. The command 
nice -x utility, for example, would be treated the same as the command nice —1 utility. If the 
user does not have appropriate privileges, this results in a "permission denied" error. This is 
considered a bug. 

When a user without appropriate privileges gives a negative increment, System V treats it like 
the command nice -0 utility, while 4.3 BSD writes a "permission denied" message and does not 
run the utility. Neither was considered clearly superior, so the behavior was left unspecified. 

The C shell has a built-in version of nice that has a different interface from the one described in 
this volume of IEEE Std. 1003.1-200x. 

The term "utility" is used, rather than "command", to highlight the fact that shell compound 
commands, pipelines, and so on, cannot be used. Special built-ins also cannot be used. 
However, "utility" includes user application programs and shell scripts, not just utilities defined 
in this volume of IEEE Std. 1003.1-200x. 

Historical implementations of nice provide a nice value range of 40 or 41 discrete steps, with the 
default nice value being the midpoint of that range. By default, they lower the nice value of the 
executed utility by 10. 

Some historical documentation states that the increment value must be within a fixed range. This 
is misleading; the valid increment values on any invocation are determined by the current 
process nice value, which is not always the default. 

The definition of nice value is not intended to suggest that all processes in a system have 
priorities that are comparable. Scheduling policy extensions such as the realtime priorities in 
POSIX.4 make the notion of a single underlying priority for all scheduling policies problematic. 
Some systems may implement the nice -related features to affect all processes on the system, 
others to affect just the general time-sharing activities implied by this volume of 
IEEE Std. 1003.1-200x, and others may have no effect at all. Because of the use of 
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26772 "implementation-dependent” in nice and renice, a wide range of implementation strategies are 

26773 possible. 

26774 FUTURE DIRECTIONS 

26775 None. 

26776 SEE ALSO 

26777 renice 

26778 CHANGE HISTORY 

26779 First released in Issue 4. 

26780 Issue 6 

26781 This utility is now marked as part of the User Portability Utilities option. 

26782 The obsolescent SYNOPSIS is removed. 
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26783 NAME 

26784 nl — line numbering filter 

26785 SYNOPSIS 

26786 XSI 

26787 

26788 

26789 DESCRIPTION 

26790 The nl utility shall read lines from the named file or the standard input if no file is named and 

26791 shall reproduce the lines to standard output. Lines shall be numbered on the left. Additional 

26792 functionality may be provided in accordance with the command options in effect. 

26793 The nl utility views the text it reads in terms of logical pages. Line numbering is reset at the start 

26794 of each logical page. A logical page consists of a header, a body, and a footer section. Empty 

26795 sections are valid. Different line numbering options are independently available for header, 

26796 body, and footer (for example, no numbering of header and footer lines while numbering blank 

26797 lines only in the body). 

26798 The starts of logical page sections are signaled by input lines containing nothing but the 

26799 following delimiter characters: 

26800 
26801 
26802 
26803 


26804 

Unless otherwise specified, nl assumes the text being read is in a single logical page body. 

26805 OPTIONS 

26806 The nl utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

26807 Section 12.2, Utility Syntax Guidelines. Only one file can be named. 

26808 

The following options shall be supported: 

26809 

26810 

-b type 

Specify which logical page body lines shall be numbered. Recognized types and 
their meaning are: 

26811 


a Number all lines. 

26812 


t Number only non-empty lines. 

26813 


n No line numbering. 

26814 

26815 


pstring Number only lines that contain the basic regular expression specified in 
string. 

26816 


The default type for logical page body is t (text lines numbered). 

26817 

26818 

26819 

26820 

-d delim 

Specify the delimiter characters that indicate the start of a logical page section. 
These can be changed from the default characters " \" to two user-specified 
characters. If only one character is entered, the second character remains the 
default character ' . 

26821 

26822 

-f type 

Specify the same as b type except for footer. The default for logical page footer is n 
(no lines numbered). 

26823 

26824 

-h type 

Specify the same as b type except for header. The default type for logical page 
header is n (no lines numbered). 


Line 

Start of 

\:\:\: 

\:\: 

\ : 

Header 

Body 

Footer 


nl [—p][—b type ][—d delim ][—f type ][—h type ][—1 incr ][—1 num ][—n format] 
[—s sep] [— v startnum] [—w width][file] 
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26828 
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-i incr Specify the increment value used to number logical page lines. The default is 1. 

-1 mini Specify the number of blank lines to be considered as one. For example, -1 2 results 

in only the second adjacent blank line being numbered (if the appropriate -h a, 
-b a, or -f a option is set). The default is 1. 

-n format Specify the line numbering format. Recognized values are: In, left justified, leading 

zeros suppressed; rn, right justified, leading zeros suppressed; rz, right justified, 
leading zeros kept. The default format is rn (right justified). 

-p Specify that numbering should not be restarted at logical page delimiters. 

-s sep Specify the characters used in separating the line number and the corresponding 

text line. The default sep is a <tab>. 

-v startnum Specify the initial value used to number logical page lines. The default is 1. 

-w ividth Specify the number of characters to be used for the line number. The default zvidth 
is 6. 


OPERANDS 

The following operand shall be supported: 

file A path name of a text file to be line-numbered. 

STDIN 

The standard input is a text file that is used if no file operand is given. 

INPUT FILES 

The input file named by the file operand is a text file. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of nl: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements within regular expressions. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the behavior of character classes within regular 
expressions, and for deciding which characters are in character class graph (for the 
-b t, -f t, and -h t options). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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26867 

26868 

26869 

26870 

26871 

26872 

26873 

26874 

26875 

26876 

26877 

26878 

26879 

26880 
26881 

26882 

26883 

26884 

26885 

26886 

26887 

26888 

26889 

26890 

26891 

26892 

26893 

26894 

26895 

26896 

26897 

26898 

26899 

26900 

26901 

26902 

26903 

26904 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall be a text file in the following format: 

"%s%s%s", <line number>, <separator>, <input line> 
where < line number> is one of the following numeric formats: 

% 6d When the rn format is used (the default; see -n). 

%0 6d When the rz format is used. 

%—6d When the In format is used. 

<empty> When line numbers are suppressed for a portion of the page; the <separator> is also 

suppressed. 

In the preceding list, the number 6 is the default width; the -w option can change this value. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

In using the -d delim option, care should be taken to escape characters that have special meaning 
to the command interpreter. 

EXAMPLES 

The command: 

nl —v 10 —i 10 —d \!+ filel 

numbers filel starting at line number 10 with an increment of 10. The logical page delimiter is 
"! +". Note that the ' !' has to be escaped when using csh as a command interpreter because of 
its history substitution syntax. For ksh and sh the escape is not necessary, but does not do any 
harm. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

The intermingling of the file operand with the options is an obsolescent feature that is removed 
from a future issue. 
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26905 SEE ALSO 

26906 pr 

26907 CHANGE HISTORY 

26908 First released in Issue 2. 

26909 Issue 4 

26910 Format reorganized. 

26911 Utility Syntax Guideline support mandated. 

26912 Internationalized environment variable support mandated. 

26913 Issue 5 

26914 The option [-f type] is added to the SYNOPSIS. The option descriptions are presented in 

26915 alphabetic order. The description of -bt is changed to "Number only non-empty lines". 

26916 Issue 6 

26917 The obsolescent behavior allowing the options to be intermingled with the optional file operand 

26918 is removed. 
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26919 

26920 

26921 

26922 

26923 

26924 

26925 

26926 

26927 

26928 

26929 

26930 

26931 

26932 

26933 

26934 

26935 

26936 

26937 

26938 

26939 

26940 

26941 

26942 

26943 

26944 

26945 

26946 

26947 

26948 

26949 

26950 

26951 

26952 

26953 

26954 

26955 


NAME 

nm — write the name list of an object file (DEVELOPMENT) 

SYNOPSIS 

UP SD xsinm [—APv] [—efox] [ —g | —u] [—t format ] file. . . 

DESCRIPTION 

This utility shall be provided on systems that support both the User Portability Utilities option 
and the Software Development Utilities option. On other systems it is optional. Certain options 
are only available on XSI-conformant systems. 

The nm utility shall display symbolic information appearing in the object file, executable file or 
object-file library named by file. If no symbolic information is available for a valid input file, the 
nm utility shall report that fact, but not consider it an error condition. 

xsi The default base used when numeric values are written is decimal. 

OPTIONS 

The nm utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-A Write the full path name or library name of an object on each line, 

xsi -e Write only external (global) and static symbol information. 

xsi -f Produce full output. Write redundant symbols (.text, .data, and .bss), normally 

suppressed. 

-g Write only external (global) symbol information. 

xsi -o Write numeric values in octal (equivalent to -t o). 

-P Write information in a portable output format, as specified in the STDOUT section. 

-t format Write each numeric value in the specified format. The format shall be dependent 

on the single character used as the format option-argument: 

xsi d The offset is written in decimal (default). 

o The offset is written in octal. 

x The offset is written in hexadecimal. 

-u Write only undefined symbols. 

-v Sort output by value instead of alphabetically. 

xsi -x Write numeric values in hexadecimal (equivalent to -t x). 

OPERANDS 

The following operand shall be supported: 

file A path name of an object file, executable file, or object-file library. 

STDIN 

See the INPUT FILES section. 
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26956 

26957 

26958 

26959 

26960 

26961 

26962 

26963 

26964 

26965 

26966 

26967 

26968 

26969 

26970 

26971 

26972 

26973 

26974 

26975 

26976 

26977 

26978 

26979 

26980 

26981 

26982 

26983 

26984 

26985 

26986 

26987 

26988 

26989 

26990 

26991 

26992 

26993 

26994 

26995 

26996 


INPUT FILES 

The input file shall be an object file, an object-file library whose format is the same as those I 
produced by the ar utility for link editing, or an executable file. The nm utility may accept 
additional implementation-dependent object library formats for the input file. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of nm: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for character collation information for the symbol-name and 
symbol-value collation sequences. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

If symbolic information is present in the input files, then for each file or for each member of an 
archive, the nm utility shall write the following information to standard output. By default, the 
format is unspecified, but the output shall be sorted alphabetically by symbol name: 

• Library or object name, if -A is specified 

• Symbol name 

• Symbol type, which shall either be one of the following single characters or an 
implementation-dependent type represented by a single character: 

A Global absolute symbol. 

a Local absolute symbol. 

B Global "bss" (that is, uninitialized data space) symbol, 
b Local bss symbol. 

D Global data symbol, 
d Local data symbol. 

T Global text symbol, 
t Local text symbol. 


Commands and Utilities, Issue 6 


707 



26997 

26998 

26999 

27000 

27001 

27002 

27003 

27004 

27005 

27006 

27007 

27008 

27009 

27010 

27011 

27012 

27013 

27014 

27015 

27016 

27017 

27018 

27019 

27020 

27021 

27022 

27023 

27024 

27025 

27026 

27027 

27028 

27029 

27030 

27031 

27032 

27033 


nm 


Utilities 


U Undefined symbol. 

• Value of the symbol 

• The size associated with the symbol, if applicable 

This information may be supplemented by additional information specific to the 
implementation. 

If the -P option is specified, the previous information shall be displayed using the following 
portable format. The three versions differ depending on whether -t d, -t o, or -t x was specified, 
respectively: 


"%s%s %s %d 
<value>, 

%d\n", <library/object 
<size> 

name>, 

<name>, 

<type>, 

" %s%s %s %o 
<value>, 

%o\n", <library/object 
<size> 

name>, 

<name>, 

<type>, 

"%s%s %s %x 

%x\n", <library/object 

name>, 

<name>, 

<type>, 


<value>, <size> 


where 

<libmry/object name> shall be formatted as follows: 

• If -A is not specified, <library/object name> shall be an empty string. 

• If -A is specified and the corresponding file operand does not name a library: 

"%s: ", <file> 

• If -A is specified and the corresponding file operand names a library. In this case, <object file> 
shall name the object file in the library containing the symbol being described: 

"%s[%s]: ", <file>, <object file> 

If -A is not specified, then if more than one file operand is specified or if only one file operand is 
specified and it names a library, nm shall write a line identifying the object containing the 
following symbols before the lines containing those symbols, in the form: 

• If the corresponding file operand does not name a library: 

"%s : \n", <file> 

• If the corresponding file operand names a library; in this case, <object file> shall be the name 
of the file in the library containing the following symbols: 

"%s[%s]:\n", <file>, <object file> 

If -P is specified, but -t is not, the format shall be as if -t x had been specified. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 
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27034 EXIT STATUS 

27035 The following exit values shall be returned: 

27036 0 Successful completion. 

27037 >0 An error occurred. 

27038 CONSEQUENCES OF ERRORS 

27039 Default. 

27040 APPLICATION USAGE 

27041 Mechanisms for dynamic linking make this utility less meaningful when applied to an 

27042 executable file because a dynamically linked executable may omit numerous library routines 

27043 that would be found in a statically linked executable. 

27044 EXAMPLES 

27045 None. 

27046 RATIONALE 

27047 Historical implementations of nm have used different bases for numeric output and supplied 

27048 different default types of symbols that were reported. The -t format option, similar to that used 

27049 in od and strings, can be used to specify the numeric base; -g and -u can be used to restrict the 

27050 amount of output or the types of symbols included in the output. 

27051 The option list was significantly reduced from that provided by historical implementations. 

27052 The nm description is a subset of both the System V and BSD nm utilities with no specified 

27053 default output. 

27054 It was recognized that mechanisms for dynamic linking make this utility less meaningful when 

27055 applied to an executable file (because a dynamically linked executable file may omit numerous 

27056 library routines that would be found in a statically linked executable file), but the value of nm 

27057 during software development was judged to outweigh other limitations. 

27058 The compromise of using -t format versus using -d, -o, and other similar options was necessary 

27059 because of differences in the meaning of -o between implementations. The -o option from BSD 

27060 has been provided here as -A to avoid confusion with the -o from System V (which has been 

27061 provided here as -t and as -o on XSI-conformant systems). 

27062 The default output format of nm is not specified because of differences in historical 

27063 implementations. The -P option was added to allow some type of portable output format. After 

27064 a comparison of the different formats used in SunOS, BSD, SVR3, and SVR4, it was decided to 

27065 create one that did not match the current format of any of these four systems. The format 

27066 devised is easy to parse by humans, easy to parse in shell scripts, and does not need to vary 

27067 depending on locale (because no English descriptions are included). All of the systems currently 

27068 have the information available to use this format. 

27069 The format given in nm STDOUT uses spaces between the fields, which may be any number of 

27070 <blank>s required to align the columns. The single-character types were selected to match 

27071 historical practice, and the requirement that implementation additions also be single characters 

27072 made parsing the information easier for shell scripts. 

27073 FUTURE DIRECTIONS 

27074 None. 

27075 SEE ALSO 

27076 ar, c89 
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27077 CHANGE HISTORY 

27078 First released in Issue 2. 

27079 Issue 4 

27080 Aligned with the ISO/IEC 9945-2:1993 standard. 

27081 Issue 6 

27082 This utility is now marked as supported when both the User Portability Utilities option and the 

27083 Software Development Utilities option are supported. 
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27084 NAME 

27085 nohup — invoke a utility immune to hangups 

27086 SYNOPSIS 

27087 nohup utility [argument...] 

27088 DESCRIPTION 

27089 The nohup utility shall invoke the utility named by the utility operand with arguments supplied 

27090 as the argument operands. At the time the named utility is invoked, the SIGHUP signal shall be 

27091 set to be ignored. 

27092 If the standard output is a terminal, all output written by the named utility to its standard output 

27093 shall be appended to the end of the file nohup.out in the current directory. If nohup.out cannot 

27094 be created or opened for appending, the output shall be appended to the end of the file 

27095 nohup.out in the directory specified by the HOME environment variable. If neither file can be 

27096 created or opened for appending, utility shall not be invoked. If a file is created, the file's 

27097 permission bits shall be set to S_IRUSR I S_IWUSR. 

27098 If the standard error is a terminal, all output written by the named utility to its standard error 

27099 shall be redirected to the same file descriptor as the standard output. 

27100 OPTIONS 

27101 None. 


27102 OPERANDS 

27103 The following operands shall be supported: 


27104 utility 

27105 

27106 argument 

27107 

27108 STDIN 

27109 Not used. 


The name of a utility that is to be invoked. If the utility operand names any of the 
special built-in utilities in Section 2.14 on page 96, the results are undefined. 

Any string to be supplied as an argument when invoking the utility named by the 
utility operand. 


27110 INPUT FILES 

27111 None. 


27112 ENVIRONMENT VARIABLES 

27113 The following environment variables shall affect the execution of nohup: 


27114 

27115 

27116 


HOME Determine the path name of the user's home directory: if the output file nohup.out 
cannot be created in the current directory, the nohup utility shall use the directory 
named by HOME to create the file. 


27117 

27118 

27119 

27120 

27121 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility behav se as if none of the variables had been 
defined. 


27122 

27123 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


27124 

27125 

27126 


LCJZTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 
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27127 

27128 

27129 

27130 

27131 

27132 

27133 

27134 

27135 

27136 

27137 

27138 

27139 

27140 

27141 

27142 

27143 

27144 

27145 

27146 

27147 

27148 

27149 

27150 

27151 

27152 

27153 

27154 

27155 

27156 

27157 

27158 

27159 

27160 

27161 

27162 

27163 

27164 

27165 

27166 

27167 

27168 

27169 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Determine the search path that is used to locate the utility to be invoked. See the I 

System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, I 
Environment Variables. I 

ASYNCHRONOUS EVENTS 

The nohup utility shall take the standard action for all signals except that SIGHUP shall be 
ignored. 

STDOUT 

If the standard output is not a terminal, the standard output of nohup shall be the standard 
output generated by the execution of the utility specified by the operands. Otherwise, nothing 
shall be written to the standard output. 

STDERR 

If the standard output is a terminal, a message shall be written to the standard error, indicating 
the name of the file to which the output is being appended. The name of the file shall be either 

nohup.out or $HOME/nohup.out. 

OUTPUT FILES 

If the standard output is a terminal, all output written by the named utility to the standard 
output and standard error is appended to the file nohup.out, which is created if it does not 
already exist. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

126 The utility specified by utility was found but could not be invoked. 

127 An error occurred in the nohup utility or the utility specified by utility could not be 
found. 

Otherwise, the exit status of nohup shall be that of the utility specified by the utility operand. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The command, env, nice, nohup, time, and xargs utilities have been specified to use exit code 127 if 
an error occurs so that applications can distinguish "failure to find a utility" from "invoked 
utility exited with an error indication". The value 127 was chosen because it is not commonly 
used for other meanings; most utilities use small values for "normal error conditions" and the 
values above 128 can be confused with termination due to receipt of a signal. The value 126 was 
chosen in a similar manner to indicate that the utility could be found, but not invoked. Some 
scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction 
between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 
exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 
any other reason. 
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27170 EXAMPLES 

27171 It is frequently desirable to apply nohup to pipelines or lists of commands. This can be done by 

27172 placing pipelines and command lists in a single file; this file can then be invoked as a utility, and 

27173 the nohup applies to everything in the file. 

27174 Alternatively, the following command can be used to apply nohup to a complex command: 

27175 nohup sh —c ' complex-command-line' 

27176 RATIONALE 

27177 The 4.3 BSD version ignores SIGTERM and SIGHUP, and if ./nohup.out cannot be used, it fails 

27178 instead of trying to use $HOME/nohup.out. 

27179 The csh utility has a built-in version of nohup that acts differently from the POSIX Shell and 

27180 Utilities nohup. 

27181 The term utility is used, rather than command, to highlight the fact that shell compound 

27182 commands, pipelines, special built-ins, and so on, cannot be used directly. However, utility 

27183 includes user application programs and shell scripts, not just the standard utilities. 

27184 Historical versions of the nohup utility use default file creation semantics. Some more recent 

27185 versions use the permissions specified here as an added security precaution. 

27186 Some historical implementations ignore SIGQUIT in addition to SIGHUP; others ignore 

27187 SIGTERM. An early proposal allowed, but did not require, SIGQUIT to be ignored. Several 

27188 reviewers objected that nohup should only modify the handling of SIGHUP as required by this 

27189 volume of IEEE Std. 1003.1-200x. 

27190 FUTURE DIRECTIONS 

27191 None. 

27192 SEE ALSO 

27193 sh, the System Interfaces volume of IEEE Std. 1003.1-200x, signal () 

27194 CHANGE HISTORY 

27195 First released in Issue 2. 

27196 Issue 4 

27197 Aligned with the ISO/IEC 9945-2:1993 standard. 
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27198 NAME 

27199 od — dump files in various formats 

27200 SYNOPSIS 

27201 od [—v] [—A address_base] [—j skip] [-N count] [—t type_string] . . . 

27202 [file...] 

27203 xsi od [— bcdosx] [file] [ [ + ] offset [.] [b] ] 

27204 

27205 DESCRIPTION 

27206 The od utility shall write the contents of its input files to standard output in a user-specified 

27207 format. 


27208 OPTIONS 

27209 The od utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

27210 xsi Section 12.2, Utility Syntax Guidelines, except that the order of presentation of the -t options I 

27211 and the -bcdosx options is significant. 

27212 The following options shall be supported: 


27213 

27214 

27215 

27216 

27217 

27218 


-A addressjoase 

Specify the input offset base. See the EXTENDED DESCRIPTION section. The I 
application shall ensure that the addressjoase option-argument is a character. The I 
characters 'd', 'o', and 'x' specify that the offset base shall be written in I 
decimal, octal, or hexadecimal, respectively. The character ' n' specifies that the 
offset shall not be written. 


27219 xsi -b Interpret bytes in octal. This is equivalent to -t ol. 

27220 XSI 

27221 

27222 

27223 

27224 XSI 


-c Interpret bytes as characters specified by the current setting of the LCJZTYPE 

category. Certain non-graphic characters appear as C escapes: "NUL=\0", 
"BS=\b", "FF=\f", "NL=\n", "CR=\r", "HT=\t"; others appear as 3-digit octal 
numbers. 

-d Interpret word s (two-byte units) in unsigned decimal. This is equivalent to -t u2. 


27225 

27226 

27227 

27228 


-j skip Jump over skip bytes from the beginning of the input. The od utility shall read or 

seek past the first skip bytes in the concatenated input files. If the combined input 
is not at least skip bytes long, the od utility shall write a diagnostic message to 
standard error and exit with a non-zero exit status. 


27229 

27230 

27231 

27232 

27233 XSI 

27234 

27235 


By default, the skip option-argument shall be interpreted as a decimal number. 
With a leading "Ox" or "OX", the offset shall be interpreted as a hexadecimal 
number; otherwise, with a leading 'O', the offset shall be interpreted as an octal 
number. Appending the character ' b' , ' k' , or ' m' to offset shall cause it to be 
interpreted as a multiple of 512, 1024, or 1048 576 bytes, respectively. If the skip 
number is hexadecimal, any appended ' b' shall be considered to be the final 
hexadecimal digit. 


27236 

27237 

27238 

27239 

27240 

27241 


-N count Format no more than count bytes of input. By default, count shall be interpreted as 
a decimal number. With a leading "Ox" or "OX", count shall be interpreted as a 
hexadecimal number; otherwise, with a leading ' 0', it shall be interpreted as an 
octal number. If count bytes of input (after successfully skipping, if -j skip is 
specified) are not available, it shall not be considered an error; the od utility shall 
format the input that is available. 


27242 XSI 


-o Interpret word s (two-byte units) in octal. This is equivalent to -t o2. 
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27246 

27247 

27248 

27249 

27250 

27251 

27252 

27253 

27254 

27255 

27256 

27257 

27258 

27259 

27260 

27261 

27262 

27263 

27264 

27265 

27266 

27267 

27268 

27269 

27270 
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xsi -s Interpret word s (two-byte units) in signed decimal. This is equivalent to -t d2. 

-t type_string 

Specify one or more output types. See the EXTENDED DESCRIPTION section. The I 
application shall ensure that the type_string option-argument is a string specifying I 
the types to be used when writing the input data. The string shall consist of the I 
type specification characters a, c, d, f, o, u, and x, specifying named character, I 
character, signed decimal, floating point, octal, unsigned decimal, and 
hexadecimal, respectively. The type specification characters d, f, o, u, and x can be 
followed by an optional unsigned decimal integer that specifies the number of 
bytes to be transformed by each instance of the output type. The type specification 
character f can be followed by an optional F, D, or L indicating that the conversion 
should be applied to an item of type float, double, or long double, respectively. 
The type specification characters d, o, u and x can be followed by an optional C, S, 

I, or L indicating that the conversion should be applied to an item of type char, 
short, int, or long, respectively. Multiple types can be concatenated within the 
same type_string and multiple -t options can be specified. Output lines shall be 
written for each type specified in the order in which the type specification 
characters are specified. 

-v Write all input data. Without the -v option, any number of groups of output lines, 

which would be identical to the immediately preceding group of output lines 
(except for the byte offsets), shall be replaced with a line containing only an 
asterisk ('*'). 

xsi -x Interpret zvords (two-byte units) in hexadecimal. This is equivalent to -t x2. 

xsi Multiple types can be specified by using multiple -bcdostx options. Output lines are written for 

each type specified in the order in which the types are specified. 

OPERANDS 

The following operands shall be supported: 

file A path name of a file to be read. If no file operands are specified, the standard 

input shall be used. If the first character of file is a plus sign (' +') or the first 
character of the first file operand is numeric, no more than two operands are given, 

xsi and none of the -A, -j, -N, or -t options is specified, the operand is assumed to be 

an offset. 

xsi [+]offset[.][ b] 

The offset operand specifies the offset in the file where dumping is to commence. 
This operand is normally interpreted as octal bytes. If ' .' is appended, the offset 
shall be interpreted in decimal. If ' b' is appended, the offset shall be interpreted 
in units of 512 bytes. If the file argument is omitted, and none of the -A, -j, -N, or 
-t options is specified, the application shall ensure that the offset argument is I 
preceded by ' +'. I 

STDIN 

The standard input shall be used only if no file operands are specified. See the INPUT FILES 

section. 

INPUT FILES 

The input files can be any file type. 
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27287 ENVIRONMENT VARIABLES 

27288 The following environment variables shall affect the execution of od: 


27289 

27290 

27291 

27292 

27293 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


27294 

27295 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


27296 

27297 

27298 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


27299 LC_MESSAGES 

27300 Determine the locale that should be used to affect the format and contents of 

27301 diagnostic messages written to standard error. 


27302 LC_NUMERIC 

27303 Determine the locale for selecting the radix character used when writing floating- 

27304 point formatted output. 

27305 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


27306 ASYNCHRONOUS EVENTS 

27307 Default. 


27308 STDOUT 

27309 See the EXTENDED DESCRIPTION section. 


27310 STDERR 

27311 Used only for diagnostic messages. 

27312 OUTPUT FILES 

27313 None. 


27314 EXTENDED DESCRIPTION 

27315 The od utility shall copy sequentially each input file to standard output, transforming the input 

27316 xsi data according to the output types specified by the -t options or the -bcdosx options. If no 

27317 output type is specified, the default output shall be as if -t oS had been specified. I 

27318 The number of bytes transformed by the output type specifier c may be variable depending on 

27319 the LC_CTYPE category. 

27320 The default number of bytes transformed by output type specifiers d, f, o, u, and x corresponds 

27321 to the various C-language types as follows. If the c89 compiler is present on the system, these 

27322 specifiers shall correspond to the sizes used by default in that compiler. Otherwise, these sizes I 

27323 may vary among systems that conform to IEEE Std. 1003.1-200x. I 


27324 

27325 

27326 

27327 

27328 

27329 

27330 

27331 


• For the type specifier characters d, o, u, and x, the default number of bytes shall correspond 
to the size of the underlying implementation's basic integral data type. For these specifier 
characters, the implementation shall support values of the optional number of bytes to be 
converted corresponding to the number of bytes in the C-language types char, short, int, and 
long. These numbers can also be specified by an application as the characters 'C','S','I', 
and ' L' , respectively. The implementation shall also support the values 1, 2, and 4, even if it I 
provides no C-Language types of those sizes. The byte order used when interpreting numeric I 
values is implementation-dependent, but shall correspond to the order in which a constant of I 
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the corresponding type is stored in memory on the system. 

• For the type specifier character f, the default number of bytes shall correspond to the number 
of bytes in the underlying implementation's basic double precision floating-point data type. 
The implementation shall support values of the optional number of bytes to be converted 
corresponding to the number of bytes in the C-language types float, double, and long 
double. These numbers can also be specified by an application as the characters ' F', ' D', 
and ' L', respectively. 

The type specifier character a specifies that bytes are interpreted as named characters from the 
International Reference Version (IRV) of the ISO/IEC 646:1991 standard. Only the least 
significant seven bits of each byte shall be used for this type specification. Bytes with the values 
listed in the following table shall be written using the corresponding names for those characters. 

Table 4-12 Named Characters in od 


Value 

Name 

Value 

Name 

Value 

Name 

Value 

Name 

\000 

nul 

\001 

soh 

\002 

stx 

\003 

etx 

\004 

eot 

\005 

enq 

\006 

ack 

\007 

bel 

\010 

bs 

\011 

ht 

\012 

If or nl 

\013 

vt 

\014 

ft 

\015 

cr 

\016 

so 

\017 

si 

\020 

die 

\021 

del 

\022 

dc2 

\023 

dc3 

\024 

dc4 

\025 

nak 

\026 

syn 

\027 

etb 

\030 

can 

\031 

em 

\032 

sub 

\033 

esc 

\034 

fs 

\035 

gs 

\036 

rs 

\037 

us 

\040 

sp 

\177 

del 






Note: The " \ 012" value may be written either as If or nl. 

The type specifier character c specifies that bytes are interpreted as characters specified by the 
current setting of the LC_CTYPE locale category. Characters listed in the table in the System I 
Interface Definitions volume of IEEEStd. 1003.1-200x, Chapter 5, File Format Notation ("\\", I 
' \a', ' \b', ' \f', ' \n' , ' \r', ' \t', ' \v') shall be written as the corresponding escape 
sequences, except that backslash shall be written as a single backslash and a NUL shall be 
written as ' \ 0'. Other non-printable characters shall be written as one three-digit octal number 
for each byte in the character. If the size of a byte on the system is greater than nine bits, the 
format used for non-printable characters is implementation-dependent. Printable multi-byte 
characters shall be written in the area corresponding to the first byte of the character; the two- 
character sequence " * *" shall be written in the area corresponding to each remaining byte in the 
character, as an indication that the character is continued. When either the -j skip or -N count 
option is specified along with the c type specifier, and this results in an attempt to start or finish 
in the middle of a multi-byte character, the result is implementation-dependent. 

The input data shall be manipulated in blocks, where a block is defined as a multiple of the least 
common multiple of the number of bytes transformed by the specified output types. If the least 
common multiple is greater than 16, the results are unspecified. Each input block shall be 
written as transformed by each output type, one per written line, in the order that the output 
types were specified. If the input block size is larger than the number of bytes transformed by 
the output type, the output type shall sequentially transform the parts of the input block, and 
the output from each of the transformations shall be separated by one or more <blank> 
characters. 

If, as a result of the specification of the -N option or end-of-file being reached on the last input 
file, input data only partially satisfies an output type, the input shall be extended sufficiently 
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27379 with null bytes to write the last byte of the input. 

27380 Unless -A n is specified, the first output line produced for each input block shall be preceded by 

27381 the input offset, cumulative across input files, of the next byte to be written. The format of the 

27382 input offset is unspecified; however, it shall not contain any <blank> characters, shall start at the 

27383 first character of the output line, and shall be followed by one or more <blank> characters. In 

27384 addition, the offset of the byte following the last byte written shall be written after all the input 

27385 data has been processed, but shall not be followed by any <blank> characters. 

27386 If no -A option is specified, the input offset base is unspecified. 

27387 EXIT STATUS 

27388 The following exit values shall be returned: 

27389 0 All input files were processed successfully. 

27390 >0 An error occurred. 

27391 CONSEQUENCES OF ERRORS 

27392 Default. 

27393 APPLICATION USAGE 

27394 Applications are warned not to use file names starting with ' +' or a first operand starting with 

27395 a numeric character so that the old functionality can be maintained by implementations, unless 

27396 they specify one of the new options specified by the ISO/IEC 9945-2:1993 standard. To 

27397 guarantee that one of these file names is always interpreted as a file name, an application could 

27398 always specify the address base format with the -A option. 

27399 EXAMPLES 

27400 If a file containing 128 bytes with decimal values zero to 127, in increasing order, is supplied as 

27401 standard input to the command: 

27402 od —A d — t a 


27403 on an implementation using an input block size of 16 bytes, the standard output, independent of 

27404 the current locale setting, would be similar to: 


27405 

0000000 

nul 

soh 

stx 

etx 

eot 

enq 

ack 

bel 

bs 

ht 

nl 

Vt 

ff 

cr 

SO 

si 

27406 

0000016 

die 

del 

dc2 

dc3 

dc4 

nak 

syn 

etb 

can 

em 

sub 

esc 

f s 

gs 

rs 

us 

27407 

0000032 

sp 

i 

II 

# 

$ 

"6 

& 

r 

( 

) 

•k 

+ 

r 

- 


/ 

27408 

0000048 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 


r 

< 

= 

> 

9 

27409 

0000064 

@ 

A 

B 

C 

D 

E 

F 

G 

H 

I 

J 

K 

L 

M 

N 

0 

27410 

0000080 

P 

Q 

R 

S 

T 

U 

V 

W 

X 

Y 

z 

[ 

\ 

] 

A 


27411 

0000096 

> 

a 

b 

c 

d 

e 

f 

g 

h 

i 

j 

k 

i 

m 

n 

o 

27412 

27413 

0000112 

0000128 

P 

q 

r 

s 

t 

u 

V 

w 

X 

Y 

z 

{ 

i 

} 

~ 

del 


27414 Note that this volume of IEEE Std. 1003.1-200x allows nl or If to be used as the name for the 

27415 ISO/IEC 646:1991 standard IRV character with decimal value 10. The IRV names this character 

27416 If (line feed), but traditional implementations have referred to this character as newline (nl) and 

27417 the POSIX locale character set symbolic name for the corresponding character is a <newline> 

27418 character. 

27419 The command: 

27420 od —A o —t o2x2x —n 18 

27421 on a system with 32-bit words and an implementation using an input block size of 16 bytes 

27422 could write 18 bytes in approximately the following format: 
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27423 

27424 

27425 

27426 

27427 

27428 

27429 

27430 

27431 

27432 

27433 

27434 

27435 

27436 

27437 

27438 

27439 

27440 

27441 

27442 

27443 

27444 

27445 

27446 

27447 

27448 

27449 

27450 

27451 

27452 

27453 

27454 

27455 

27456 

27457 

27458 

27459 

27460 

27461 

27462 

27463 

27464 

27465 

27466 

27467 

27468 
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0000000 032056 031440 041123 042040 052516 044530 020043 031464 

342e 3320 4253 4420 554e 4958 2023 3334 

342e3320 42534420 554e4958 20233334 

0000020 032472 
353a 

353a0000 

0000022 

The command: 

od —A d —t f —t o4 —t x4 —n 24 —j 0x15 

on a system with 64-bit doubles (for example, the IEEE Std. 754:1985 standard double precision 
floating-point format) would skip 21 bytes of input data and then write 24 bytes in 
approximately the following format: 

0000000 1.00000000000000e+00 1.57350000000000e+01 

07774000000 00000000000 10013674121 35341217270 
3ff00000 00000000 402f3851 eb851eb8 

0000016 1.40668230000000e+02 

10030312542 04370303230 
40619562 23el8698 

0000024 

RATIONALE 

The od utility went through several names in early proposals, including lid, xd, and most recently 
hexdump. There were several objections to all of these based on the following reasons: 

• The hd and xd names conflicted with historical utilities that behaved differently. 

• The hexdump description was much more complex than needed for a simple dump utility. 

• The od utility has been available on all historical implementations and there was no need to 
create a new name for a utility so similar to the historical od utility. 

The original reasons for not standardizing historical od were also fairly widespread. Those 
reasons are given below along with rationale explaining why the standard developers believe 
that this version does not suffer from the indicated problem: 

• The BSD and System V versions of od have diverged, and the intersection of features 
provided by both does not meet the needs of the user community. In fact, the System V 
version only provides a mechanism for dumping octal bytes and shorts, signed and unsigned 
decimal shorts, hexadecimal shorts, and ASCII characters. BSD added the ability to dump 
floats, doubles, named ASCII characters, and octal, signed decimal, unsigned decimal, and 
hexadecimal longs. The version presented here provides more normalized forms for 
dumping bytes, shorts, ints, and longs in octal, signed decimal, unsigned decimal, and 
hexadecimal; float, double, and long double; and named ASCII as well as current locale 
characters. 

• It would not be possible to come up with a compatible superset of the BSD and System V 
flags that met the requirements of the standard developers. The historical default od output is 
the specified default output of this utility. None of the option letters chosen for this version 
of od conflict with any of the options to historical versions of od. 

• On systems with different sizes for short, int, and long, there was no way to ask for dumps 
of ints, even in the BSD version. Because of the way options are named, the namespace could 
not be extended to solve these problems. This is why the -t option was added (with type 
specifiers more closely matched to the printf() formats used in the rest of this volume of 
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27473 

27474 

27475 

27476 

27477 
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27486 

27487 

27488 

27489 
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27502 

27503 

27504 

27505 

27506 

27507 

27508 

27509 

27510 

27511 
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27513 

27514 

27515 

27516 
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IEEE Std. 1003.1-200x) and the optional field sizes were added to the d, f, o, u, and x type 
specifiers. It is also one of the reasons why the historical practice was not mandated as a 
required obsolescent form of od. (Although the old versions of od are not listed as an 
obsolescent form, implementations are urged to continue to recognize the older forms for 
several more years.) The a, c, f, o, and x types match the meaning of the corresponding 
format characters in the historical implementations of od except for the default sizes of the 
fields converted. The d format is signed in this volume of IEEE Std. 1003.1-200x to match the 
print /{) notation. (Historical versions of od used d as a synonym for u in this version. The 
System V implementation uses s for signed decimal; BSD uses i for signed decimal and s for 
null-terminated strings.) Other than d and u, all of the type specifiers match format 
characters in the historical BSD version of od. 

The sizes of the C-language types char, short, int, long, float, double, and long double are 
used even though it is recognized that there may be zero or more than one compiler for the C 
language on an implementation and that they may use different sizes for some of these types. 
(For example, one compiler might use 2 bytes shorts, 2 bytes ints, and 4 bytes longs, while 
another compiler (or an option to the same compiler) uses 2 bytes shorts, 4 bytes ints, and 4 
bytes longs.) Nonetheless, there has to be a basic size known by the implementation for 
these types, corresponding to the values reported by invocations of the getconf utility when 
called with system_var operands {UCHAR_MAX}, {USHORT_MAX}, |UINT_MAX}, and 
|ULONG_MAX} for the types char, short, int, and long, respectively. There are similar 
constants required by the ISO C standard, but not required by the System Interfaces volume 
of IEEE Std. 1003.1-200x or this volume of IEEE Std. 1003.1-200x. They are 
{FLT_MANT_DIG}, {DBL_MANT_DIG}, and |LDBL_MANT_DIG} for the types float, 
double, and long double, respectively. If the optional c89 utility is provided by the 
implementation and used as specified by this volume of IEEE Std. 1003.1-200x, these are the 
sizes that would be provided. If an option is used that specifies different sizes for these types, 
there is no guarantee that the od utility is able to interpret binary data output by such a 
program correctly. 

This volume of IEEE Std. 1003.1-200x requires that the numeric values of these lengths be 
recognized by the od utility and that symbolic forms also be recognized. Thus, a portable 
application can always look at an array of unsigned long data elements using od -t nL. 

• The method of specifying the format for the address field based on specifying a starting 
offset in a file unnecessarily tied the two together. The -A option now specifies the address 
base and the -S option specifies a starting offset. 

• It would be difficult to break the dependence on U.S. ASCII to achieve an internationalized 
utility. It does not seem to be any harder for od to dump characters in the current locale than 
it is for the ed or sed 1 commands. The c type specifier does this without difficulty and is 
completely compatible with the historical implementations of the c format character when 
the current locale uses a superset of the ISO/IEC 646:1991 standard as a codeset. The a type 
specifier (from the BSD a format character) was left as a portable means to dump ASCII (or 
more correctly ISO/IEC 646:1991 standard (IRV)) so that headers produced by pax could be 
deciphered even on systems that do not use the ISO/IEC 646:1991 standard as a subset of 
their base codeset. 

The use of " * * " as an indication of continuation of a multi-byte character in c specifier output 
was chosen based on seeing an implementation that uses this method. The continuation bytes 
have to be marked in a way that is not ambiguous with another single-byte or multi-byte 
character. 

An early proposal used -S and -n, respectively, for the -j and -N options eventually selected. 
These were changed to avoid conflicts with historical implementations. 
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27518 The original standard specified -t o2 as the default when no output type was given. This was I 

27519 changed to -t oS (the length of a short) to accommodate a supercomputer implementation that I 

27520 historically used 64 bits as its default (and that defined shorts as 64 bits). This change should not I 

27521 affect portable applications. The requirement to support lengths of 1, 2, and 4 was added at the I 

27522 same time to address an historical implementation that had no two-byte data types in its C I 

27523 compiler. I 

27524 FUTURE DIRECTIONS 

27525 All option and operand interfaces marked as extensions may be withdrawn in a future issue. I 

27526 SEE ALSO 

27527 sed 

27528 CHANGE HISTORY 

27529 First released in Issue 2. 

27530 Issue 4 

27531 Aligned with the ISO/IEC 9945-2:1993 standard. 

27532 Issue 4, Version 2 

27533 The description of the -c option is made dependent on the current setting of the LC_CTYPE 

27534 category, and a reference to the POSIX locale is deleted. 

27535 Issue 5 

27536 In the description of the -c option, the phrase "This is equivalent to -t c." is deleted. 

27537 The FUTURE DIRECTIONS section has been modified. I 

27538 Issue 6 I 

27539 The od utility is changed to remove the assumption that short was a two-byte entity, as per the I 

27540 revisions in the IEEE P1003.2b draft standard. I 

27541 The normative text is reworded to avoid use of the term "must" for application requirements. I 
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27542 NAME 

27543 paste — 

27544 SYNOPSIS 

27545 paste 

27546 DESCRIPTION 


merge corresponding or subsequent lines of files 


[—s][—d list] file... 


27547 

27548 

27549 

27550 

27551 

27552 

27553 

27554 


The paste utility shall concatenate the corresponding lines of the given input files, and writes the 
resulting lines to standard output. 

The default operation of paste shall concatenate the corresponding lines of the input files. The 
<newline> character of every line except the line from the last input file shall be replaced with a 
<tab> character. 

If an end-of-file condition is detected on one or more input files, but not all input files, paste shall 
behave as though empty lines were read from the files on which end-of-file was detected, unless 
the -s option is specified. 


27555 OPTIONS 

27556 

27557 

27558 

27559 

27560 

27561 

27562 

27563 

27564 

27565 

27566 

27567 

27568 

27569 

27570 

27571 

27572 

27573 

27574 

27575 

27576 

27577 

27578 

27579 

27580 

27581 

27582 

27583 


Definitions volume of I 

I 


The paste utility shall conform to the System Interface 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported: 

-d list Unless a backslash character appears in list, each character in list is an element 

specifying a delimiter character. If a backslash character appears in list, the 
backslash character and one or more characters following it are an element 
specifying a delimiter character as described below. These elements specify one or 
more delimiters to use, instead of the default <tab> character, to replace the 
<newline> character of the input lines. The elements in list shall be used circularly; 
that is, when the list is exhausted the first element from the list is reused. When the 
-s option is specified: 

• The last <newline> character in a file shall not be modified. 

• The delimiter shall be reset to the first element of list after each file operand is 
processed. 

When the -s option is not specified: 

• The <newline> characters in the file specified by the last file operand shall not 
be modified. 

• The delimiter shall be reset to the first element of list each time a line is 
processed from each file. 

If a backslash character appears in list, it and the character following it shall be 
used to represent the following delimiter characters: 

\n <newline> character. 

\t <tab> character. 

\ \ Backslash character. 

\0 Empty string (not a null character). If ' \ 0' is immediately followed by the 
character ' x', the character ' X' , or any character defined by the LC_CTYPE 
digit keyword (see the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 7, Locale), the results are unspecified. 
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27584 


If any other characters follow the backslash, the results are unspecified. 


27585 -S 

27586 

27587 


Concatenate all of the lines of each separate input file in command line order. The 
<newline> character of every line except the last line in each input file shall be 
replaced with the <tab> character, unless otherwise specified by the -d option. 


27588 OPERANDS 

27589 The following operand shall be supported: 


27590 file 

27591 

27592 

27593 


A path name of an input file. If is specified for one or more of the files, the 
standard input shall be used; the standard input shall be read one line at a time, 
circularly, for each instance of ' . Implementations shall support pasting of at 

least 12 file operands. 


27594 STDIN 

27595 The standard input shall be used only if one or movefile operands is ' - '. See the INPUT FILES 

27596 section. 


27597 INPUT FILES 

27598 The input files shall be text files, except that line lengths shall be unlimited. 

27599 ENVIRONMENT VARIABLES 


27600 

The following environment variables shall affect the execution of paste: 

27601 

27602 

27603 

27604 

27605 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

27606 

27607 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

27608 

27609 

27610 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

27611 

27612 

27613 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

27614 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


27615 ASYNCHRONOUS EVENTS 

27616 Default. 


27617 STDOUT 

27618 Concatenated lines of input files shall be separated by the <tab> character (or other characters 

27619 under the control of the -d option) and terminated by a <newline> character. 

27620 STDERR 

27621 Used only for diagnostic messages. 

27622 OUTPUT FILES 

27623 None. 


27624 EXTENDED DESCRIPTION 

27625 None. 
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27626 EXIT STATUS 

27627 The following exit values shall be returned: 

27628 0 Successful completion. 

27629 >0 An error occurred. 

27630 CONSEQUENCES OF ERRORS 

27631 If one or more input files cannot be opened when the -s option is not specified, a diagnostic 

27632 message shall be written to standard error, but no output is written to standard output. If the -s 

27633 option is specified, the paste utility shall provide the default behavior described in Section 1.11 

27634 on page 25. 

27635 APPLICATION USAGE 

27636 When the escape sequences of the list option-argument are used in a shell script, they must be 

27637 quoted; otherwise, the shell treats the ' \' as a special character. 

27638 Portable applications should only use the specific backslash escaped delimiters presented in this 

27639 volume of IEEE Std. 1003.1-200x. Historical implementations treat ' \x', where ' x' is not in this 

27640 list, as ' x', but future implementations are free to expand this list to recognize other common 

27641 escapes similar to those accepted by print/ and other standard utilities. 

27642 Most of the standard utilities work on text files. The c»t utility can be used to turn files with 

27643 arbitrary line lengths into a set of text files containing the same data. The paste utility can be used 

27644 to create (or recreate) files with arbitrary line lengths. For example, if file contains long lines: 

27645 cut —b 1—500 —n file > filel 

27646 cut —b 501— —n file > file2 

27647 creates filel (a text file) with lines no longer than 500 bytes (plus the <newline> character) and 

27648 file2 that contains the remainder of the data from file. Note that file2 is not a text file if there 

27649 are lines in file that are longer than 500 + |LINE_MAX} bytes. The original file can be recreated 

27650 from filel and file2 using the command: 

27651 paste —d "\0" filel file2 > file 

27652 The commands: 

27653 paste —d "\0" ... 

27654 paste -d "" ... 

27655 are not necessarily equivalent; the latter is not specified by this volume of IEEE Std. 1003.1-200x 

27656 and may result in an error. The construct ' \0' is used to mean "no separator" because 

27657 historical versions of paste did not follow the syntax guidelines, and the command: 

27658 paste —d"" . . . 

27659 could not be handled properly by getopt (). 

27660 EXAMPLES 

27661 1. Write out a directory in four columns: 

27662 Is | paste - - - - 

27663 2. Combine pairs of lines from a file into single lines: 

27664 paste —s —d "\t\n" file 
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27665 RATIONALE 

27666 None. 

27667 FUTURE DIRECTIONS 

27668 None. 

27669 SEE ALSO 

27670 cut,grep,pr 

27671 CHANGE HISTORY 

27672 First released in Issue 2. 

27673 Issue 4 

27674 Aligned with the ISO/IEC 9945-2:1993 standard. 

27675 Issue 6 

27676 The normative text is reworded to avoid use of the term "must” for application requirements. 
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27677 NAME 

27678 patch — apply changes to files 

27679 SYNOPSIS 

27680 UP patch [— blNR] [ —c | —e | — n] [— d dir] [— D define ] [— i patch file] 

27681 [—o outfile] [—p num] [—r rejectfile] [file] 

27682 


27683 DESCRIPTION 

27684 The patch utility shall read a source (patch) file containing any of the three forms of difference 

27685 (diff) listings produced by the cliff utility (normal, context or in the style of ed) and apply those 

27686 differences to a file. By default, patch shall read from the standard input. 

27687 The patch utility shall attempt to determine the type of the diff listing, unless overruled by a -c, 

27688 -e, or -n option. 

27689 If the patch file contains more than one patch, patch shall attempt to apply each of them as if they 

27690 came from separate patch files. (In this case, the application shall ensure that the name of the I 

27691 patch file is determinable for each diff listing.) I 


27692 OPTIONS 

27693 The patch utility shall conform to the System Interface Definitions volume of I 

27694 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

27695 The following options shall be supported: 


27696 -b 

27697 

27698 

27699 

27700 

27701 


Save a copy of the original contents of each modified file, before the differences are 
applied, in a file of the same name with the suffix .orig appended to it. If the file 
already exists, it shall be overwritten; if multiple patches are applied to the same 
file, the .orig file shall be written only for the first patch. When the -o outfile option 
is also specified, file .orig shall not be created but, if outfile already exists, 
outfile .orig shall be created. 


27702 -C 

27703 


Interpret the patch file as a context difference (the output of the utility diff when 
the -c or -C options are specified). 


27704 

27705 


-d dir Change the current directory to dir before processing as described in the 

EXTENDED DESCRIPTION section. 


27706 

-D define 

Mark changes with one of the following C preprocessor constructs: 

27707 


#ifdef define 

27708 



27709 


#endif 

27710 


#ifndef define 

27711 



27712 


#endif 


27713 


optionally combined with the C preprocessor construct #else. 


27714 -e 


Interpret the patch file as an ed script, rather than a diff script. 


27715 

27716 


-i patchfile 


Read the patch information from the file named by the path name patchfile, rather 
than the standard input. 


27717 -1 

27718 

27719 


(The letter ell.) Cause any sequence of <blank> characters in the difference script to 
match any sequence of <blank> characters in the input file. Other characters shall 
be matched exactly. 
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27720 -n 


Interpret the script as a normal difference. 


27721 -N 

27722 


Ignore patches where the differences have already been applied to the file; by 
default, already-applied patches shall be rejected. 


27723 

27724 

27725 

27726 

27727 

27728 


-o ontfile Instead of modifying the files (specified by the file operand or the difference 
listings) directly, write a copy of the file referenced by each patch, with the 
appropriate differences applied, to outfile. Multiple patches for a single file shall 
be applied to the intermediate versions of the file created by any previous patches, 
and shall result in multiple, concatenated versions of the file being written to 
outfile. 


27729 

27730 

27731 

27732 

27733 

27734 


-p man For all path names in the patch file that indicate the names of files to be patched, 
delete man path name components from the beginning of each path name. If the 
path name in the patch file is absolute, any leading slashes shall be considered the 
first component (that is, -p 1 shall remove the leading slashes). Specifying -p 0 
shall cause the full path name to be used. If -p is not specified, only the basename 
(the final path name component) shall be used. 


27735 -R 

27736 

27737 

27738 

27739 

27740 

27741 

27742 


Reverse the sense of the patch script; that is, assume that the difference script was 
created from the new version to the old version. The -R option cannot be used 
with ed scripts. The patch utility attempts to reverse each portion of the script 
before applying it. Rejected differences shall be saved in swapped format. If this 
option is not specified, and until a portion of the patch file is successfully applied, 
patch attempts to apply each portion in its reversed sense as well as in its normal 
sense. If the attempt is successful, the user shall be prompted to determine if the 
-R option should be set. 


27743 

27744 

27745 


-r rejectfile Override the default reject file name. In the default case, the reject file shall have 
the same name as the output file, with the suffix .rej appended to it; see Patch 
Application on page 729. 


27746 OPERANDS 

27747 The following operand shall be supported: 

27748 file A path name of a file to patch. 


27749 STDIN 

27750 See the INPUT FILES section. 


27751 INPUT FILES 

27752 Input files shall be text files. 

27753 ENVIRONMENT VARIABLES 


27754 

The following environment variables shall affect the execution of patch: 

27755 

27756 

27757 

27758 

27759 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

27760 

27761 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

27762 

27763 

27764 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 
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27765 

27766 

27767 

27768 

27769 

27770 

27771 

27772 

27773 

27774 

27775 

27776 

27777 

27778 

27779 

27780 

27781 

27782 

27783 

27784 

27785 

27786 

27787 

27788 

27789 

27790 

27791 

27792 

27793 

27794 

27795 

27796 

27797 

27798 

27799 

27800 

27801 

27802 

27803 

27804 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

LC_TIME Determine the locale for recognizing the format of file timestamps written by the 
diff utility in a context-difference input file. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Used for diagnostic and informational messages. 

OUTPUT FILES 

The output of the patch utility, the save files (.orig suffixes) and the reject files (.rej suffixes) shall 
be text files. 

EXTENDED DESCRIPTION 

A patchfile may contain patching instructions for more than one file; file names shall be 
determined as specified in File Name Determination on page 729. When the -b option is 
specified, for each patched file, the original shall be saved in a file of the same name with the 
suffix .orig appended to it. 

For each patched file, a reject file may also be created as noted in Patch Application on page 729. 

In the absence of a -r option, the name of this file shall be formed by appending the suffix .rej to 
the original file name. 

Patchfile Format 

The patch file shall contain zero or more lines of header information followed by one or more I 
patches. Each patch shall contain zero or more lines of file name identification in the format I 
produced by diff-c, and one or more sets of diff output, which are customarily called hunks. 

The patch utility shall recognize the following expression in the header information: 

Index: pathname 

The file to be patched is named pathname. 

If all lines (including headers) within a patch begin with the same leading sequence of <blank> 
characters, the patch utility shall remove this sequence before proceeding. Within each patch, if 
the type of difference is context, the patch utility shall recognize the following expressions: 

*** filename timestamp 

The patches arose irom filename. 

- filename timestamp 

The patches should be applied to filename. 

Each hunk within a patch shall be the diff output to change a line range within the original file. I 
The line numbers for successive hunks within a patch shall occur in ascending order. I 
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27805 

27806 

27807 

27808 

27809 

27810 

27811 

27812 

27813 

27814 

27815 

27816 

27817 

27818 

27819 

27820 

27821 

27822 

27823 

27824 

27825 

27826 

27827 

27828 

27829 

27830 

27831 

27832 

27833 

27834 

27835 

27836 

27837 

27838 

27839 

27840 

27841 

27842 

27843 

27844 

27845 

27846 

27847 


XSI 


File Name Determination 

If no file operand is specified, patch shall perform the following steps to determine the file name I 
to use: I 

1. If the type of diff is context, the patch utility shall delete path name components (as I 

specified by the -p option) from the file name on the line beginning with "***", then test I 

for the existence of this file relative to the current directory (or the directory specified with I 

the -d option). If the file exists, the patch utility shall use this file name. I 

2. If the type of diff is context, the patch utility shall delete the path name components (as I 

specified by the -p option) from the file name on the line beginning with "-", then test I 

for the existence of this file relative to the current directory (or the directory specified with I 

the -d option). If the file exists, the patch utility shall use this file name. I 

3. If the header information contains a line beginning with the string Index:, the patch utility I 

shall delete path name components (as specified by the -p option) from this line, then test I 
for the existence of this file relative to the current directory (or the directory specified with I 
the -d option). If the file exists, the patch utility shall use this file name. I 

4. If an SCCS directory exists in the current directory, patch shall attempt to perform a get -e 
SCCSIs.filename command to retrieve an editable version of the file. 

5. The patch utility shall write a prompt to standard output and request a file name I 

interactively from the controlling terminal (for example, /dev/tty). I 


Patch Application 

If the -c, -e, or -n option is present, the patch utility shall interpret information within each hunk 
as a context difference, an ed difference or a normal difference, respectively. In the absence of 
any of these options, the patch utility shall determine the type of difference based on the format 
of information within the hunk. 

For each hunk, the patch utility shall begin to search for the place to apply the patch at the line 
number at the beginning of the hunk, plus or minus any offset used in applying the previous 
hunk. If lines matching the hunk context are not found, patch shall scan both forwards and 
backwards at least 1000 bytes for a set of lines that match the hunk context. 

If no such place is found and it is a context difference, then another scan shall take place, 
ignoring the first and last line of context. If that fails, the first two and last two lines of context 
shall be ignored and another scan shall be made. Implementations may search more extensively 
for installation locations. 

If no location can be found, the patch utility shall append the hunk to the reject file. The rejected 
hunk shall be written in context-difference format regardless of the format of the patch file. If the 
input was a normal or ed-style difference, the reject file may contain differences with zero lines 
of context. The line numbers on the hunks in the reject file may be different from the line 
numbers in the patch file since they shall reflect the approximate locations for the failed hunks in 
the new file rather than the old one. 

If the type of patch is an ed diff, the implementation may accomplish the patching by invoking 
the ed utility. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 


Commands and Utilities, Issue 6 


729 




patch 


Utilities 


27848 1 One or more lines were written to a reject file. 

27849 >1 An error occurred. 

27850 CONSEQUENCES OF ERRORS 

27851 Patches that cannot be correctly placed in the file shall be written to a reject file. 

27852 APPLICATION USAGE 

27853 The -R option does not work with ed scripts because there is too little information to reconstruct 

27854 the reverse operation. 

27855 The -p option makes it possible to customize a patchfile to local user directory structures 

27856 without manually editing the patchfile. For example, if the file name in the patch file was: 

27857 /curds/whey/src/blurf 1/blurf 1 . c 

27858 Setting -p 0 gives the entire path name unmodified; -p 1 gives: 

27859 curds/whey/src/blurf 1/blurf 1 . c 

27860 without the leading slash, -p 4 gives: 

27861 blurf 1/blurf 1. c 

27862 and not specifying -p at all gives: 

27863 blurf l.c . 

27864 When using -b in some file system implementations, the saving of a .orig file may produce 

27865 unwanted results. In the case of 12,13, or 14-character file names, on file systems supporting 14- 

27866 character maximum file names, the .orig file overwrites the new file. 

27867 Application writers should note that this utility need not be provided on systems that do not 

27868 support the User Portability Utilities option. 

27869 EXAMPLES 

27870 None. 

27871 RATIONALE 

27872 Some of the functionality in historical patch implementations was not specified. The following 

27873 documents those features present in historical implementations that have not been specified. 

27874 A deleted piece of functionality was the ' +' pseudo-option allowing an additional set of options 

27875 and a patch file operand to be given. This was seen as being insufficiently useful to standardize. 

27876 In historical implementations, if the string "Prereq: " appeared in the header, the patch utility 

27877 would search for the corresponding version information (the string specified in the header, 

27878 delimited by <blank>s or the beginning or end of a line or the file) anywhere in the original file. 

27879 This was deleted as too simplistic and insufficiently trustworthy a mechanism to standardize. 

27880 For example, if: 

27881 Prereq: 1.2 

27882 were in the header, the presence of a delimited 1.2 anywhere in the file would satisfy the 

27883 prerequisite. 

27884 The following options were dropped from historical implementations of patch as insufficiently 

27885 useful to standardize: 

27886 -b The -b option historically provided a method for changing the name extension of 

27887 the backup file from the default .orig. This option has been modified and retained 

27888 in this volume of IEEE Std. 1003.1-200x. 
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27889 -F The -F option specified the number of lines of a context diff to ignore when 

27890 searching for a place to install a patch. 

27891 -f The -f option historically caused patch not to request additional information from 

27892 the user. 

27893 -r The -r option historically provided a method of overriding the extension of the 

27894 reject file from the default .rej. 

27895 -s The -s option historically caused patch to work silently unless an error occurred. 

27896 -x The -x option historically set internal debugging flags. 

27897 In some file system implementations, the saving of a .orig file may produce unwanted results. In 

27898 the case of 12,13, or 14-character file names (on file systems supporting 14-character maximum 

27899 file names), the .orig file overwrites the new file. The reject file may also exceed this file name 

27900 limit. It was suggested, due to some historical practice, that a tilde (' ~') suffix be used instead 

27901 of .orig and some other character instead of the .rej suffix. This was rejected because it is not 

27902 obvious to the user which file is which. The suffixes .orig and .rej are clearer and more 

27903 understandable. 

27904 The -b option has the opposite sense in some historical implementations—do not save the .orig 

27905 file. The default case here is not to save the files, making patch behave more consistently with the 

27906 other standard utilities. 

27907 The -w option in early proposals was changed to -1 to match historical practice. 

27908 The -N option was included because without it, a non-interactive application cannot reject 

27909 previously applied patches. For example, if a user is piping the output of diff into the patch 

27910 utility, and the user only wants to patch a file to a newer version non-interactively, the -N 

27911 option is required. 

27912 Changes to the -1 option description were proposed to allow matching across <newline>s in 

27913 addition to just <blank>s. Since this is not historical practice, and since some ambiguities could 

27914 result, it is suggested that future developments in this area utilize another option letter, such as 

27915 -L. 

27916 FUTURE DIRECTIONS 

27917 None. I 

27918 SEE ALSO 

27919 ed, diff 

27920 CHANGE HISTORY 

27921 First released in Issue 4. 

27922 Issue 5 

27923 FUTURE DIRECTIONS section added. 

27924 Issue 6 

27925 This utility is now marked as part of the User Portability Utilities option. I 

27926 The description of the -D option and the steps in File Name Determination on page 729 are I 

27927 changed to match historical practice as defined in the IEEE P1003.2b draft standard. I 

27928 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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27929 

27930 

27931 

27932 

27933 

27934 

27935 

27936 

27937 

27938 

27939 

27940 

27941 

27942 

27943 

27944 

27945 

27946 

27947 

27948 

27949 

27950 

27951 

27952 

27953 

27954 

27955 

27956 

27957 

27958 

27959 

27960 

27961 

27962 

27963 

27964 

27965 

27966 

27967 


NAME 

pathchk — check path names 

SYNOPSIS 

pathchk [—p] pathname... 


DESCRIPTION 

The pathchk utility shall check that one or more path names are valid (that is, they could be used 
to access or create a file without causing syntax errors) and portable (that is, no file name 
truncation results). More extensive portability checks are provided by the -p option. 

By default, the pathchk utility shall check each component of each pathname operand based on the 
underlying file system. A diagnostic shall be written for each pathname operand that: 

• Is longer than |PATH_MAX} bytes (see Path Name Variable Values in the System Interface I 

Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers, <limits.h>) I 

• Contains any component longer than |NAME_MAX} bytes in its containing directory 

• Contains any component in a directory that is not searchable 

• Contains any character in any component that is not valid in its containing directory 

The format of the diagnostic message is not specified, but shall indicate the error detected and 
the corresponding pathname operand. 

It shall not be considered an error if one or more components of a pathname operand do not exist 
as long as a file matching the path name specified by the missing components could be created 
that does not violate any of the checks specified above. 

OPTIONS 

The pathchk utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following option shall be supported: 

-p Instead of performing checks based on the underlying file system, write a 

diagnostic for each pathname operand that: 

• Is longer than j_POSIX_PATH_MAX} bytes (see Minimum Values in the I 

System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, I 
Headers, <limits.h>) I 

• Contains any component longer than j_POSIX_NAME_MAX} bytes 

• Contains any character in any component that is not in the portable file name 
character set 


OPERANDS 

The following operand shall be supported: 
pathname A path name to be checked. 

STDIN 

Not used. 


INPUT FILES 

None. 
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27968 ENVIRONMENT VARIABLES 

27969 The following environment variables shall affect the execution of pathchk: 


27970 

27971 

27972 

27973 

27974 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


27975 

27976 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


27977 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

27978 characters (for example, single-byte as opposed to multi-byte characters in 

27979 arguments). 

27980 LC_MESSAGES 

27981 Determine the locale that should be used to affect the format and contents of 

27982 diagnostic messages written to standard error. 

27983 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

27984 ASYNCHRONOUS EVENTS 

27985 Default. 


27986 STDOUT 

27987 Not used. 


27988 STDERR 

27989 Used only for diagnostic messages. 

27990 OUTPUT FILES 

27991 None. 


27992 EXTENDED DESCRIPTION 

27993 None. 


27994 EXIT STATUS 

27995 The following exit values shall be returned: 

27996 0 All pathname operands passed all of the checks. 

27997 >0 An error occurred. 


27998 CONSEQUENCES OF ERRORS 

27999 Default. 

28000 APPLICATION USAGE 

28001 The test utility can be used to determine whether a given path name names an existing file; it 

28002 does not, however, give any indication of whether or not any component of the path name was 

28003 truncated in a directory where the _POSIX_NO_TRUNC feature is not in effect. The pathchk 

28004 utility does not check for file existence; it performs checks to determine if a path name does exist 

28005 or could be created with no path name component truncation. 

28006 The noclobber option in the shell (see the set on page 117 special built-in) can be used to 

28007 atomically create a file. As with all file creation semantics in the System Interfaces volume of 

28008 IEEE Std. 1003.1-200x, it guarantees atomic creation, but still depends on applications to agree 

28009 on conventions and cooperate on the use of files after they have been created. 
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28010 

28011 

28012 

28013 

28014 

28015 

28016 

28017 

28018 

28019 

28020 

28021 

28022 

28023 

28024 

28025 

28026 

28027 

28028 

28029 

28030 

28031 

28032 

28033 

28034 

28035 

28036 

28037 

28038 

28039 

28040 

28041 

28042 

28043 

28044 

28045 

28046 

28047 

28048 

28049 

28050 

28051 

28052 

28053 

28054 

28055 

28056 


EXAMPLES 

To verify that all path names in an imported data interchange archive are legitimate and 
unambiguous on the current system: 

pax —f archive | sed —e '/ == . */s///' I xargs pathchk 

if [ $? -eq 0 ] 

then 

pax —r —f archive 

else 

echo Investigate problems before importing files, 
exit 1 
fi 

To verify that all files in the current directory hierarchy could be moved to any system 
conforming to the System Interfaces volume of IEEE Std. 1003.1-200x that also supports the pax 
utility: 

find . —print | xargs pathchk —p 

if [ $? -eq 0 ] 

then 

pax —w —f archive . 

else 

echo Portable archive cannot be created, 
exit 1 
fi 

To verify that a user-supplied path name names a readable file and that the application can 
create a file extending the given path without truncation and without overwriting any existing 
file: 

case $— in 

*C*) reset="";; 

*) reset="set +C" 

set —C;; 

esac 

test —r "$path" && pathchk "$path.out" && 
rm "$path.out" > "$path.out" 
if [ $? —ne 0 ] ; then 

printf "%s: %s not found or %s.out fails \ 
creation checks.\n" $0 "$path" "$path" 

$reset # Reset the noclobber option in case a trap 
# on EXIT depends on it. 

exit 1 
fi 

$reset 

PROCESSING < "$path" > "$path.out" 

The following assumptions are made in this example: 

1. PROCESSING represents the code that is used by the application to use $path once it is 
verified that $path.out works as intended. 

2. The state of the noclobber option is unknown when this code is invoked and should be set 
on exit to the state it was in when this code was invoked. (The reset variable is used in this 
example to restore the initial state.) 
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28057 

28058 

28059 

28060 


3. Note the usage of: 

rm "$path.out" > "$path.out" 

a. The pathchk command has already verified, at this point, that $path.out is not 
truncated. 


28061 

28062 

28063 

28064 

28065 

28066 

28067 

28068 


b. With the noclobber option set, the shell verifies that $path.out does not already exist 
before invoking rm. 

c. If the shell succeeded in creating $path.out, rm removes it so that the application can 
create the file again in the PROCESSING step. 

d. If the PROCESSING step wants the file to exist already when it is invoked, the: 

rm "$path.out" > "$path.out" 

should be replaced with: 

> "$path.out" 


28069 which verifies that the file did not already exist, but leaves Spath.out in place for use 

28070 by PROCESSING. 

28071 RATIONALE 

28072 The pathchk utility is new, commissioned for this volume of IEEE Std. 1003.1-200x. It, along with 

28073 the set -C(noclobber) option added to the shell, replaces the mktemp, validfnam, and create utilities 

28074 that appeared in early proposals. All of these utilities were attempts to solve several common 

28075 problems: 

28076 • Verify the validity (for several different definitions of "valid”) of a path name supplied by a 

28077 user, generated by an application, or imported from an external source. 

28078 • Atomically create a file. 

28079 • Perform various string handling functions to generate a temporary file name. 

28080 The create utility, included in an early proposal, provided checking and atomic creation in a 

28081 single invocation of the utility; these are orthogonal issues and need not be grouped into a single 

28082 utility. Note that the noclobber option also provides a way of creating a lock for process 

28083 synchronization; since it provides an atomic create, there is no race between a test for existence 

28084 and the following creation if it did not exist. 

28085 Having a function like tmpnam() in the ISOC standard is important in many high-level 

28086 languages. The shell programming language, however, has built-in string manipulation 

28087 facilities, making it very easy to construct temporary file names. The names needed obviously 

28088 depend on the application, but are frequently of a form similar to: 

28089 $TMPDIR/ application_abbreviation$$ . suffix 

28090 In cases where there is likely to be contention for a given suffix, a simple shell for or while loop 

28091 can be used with the shell noclobber option to create a file without risk of collisions, as long as 

28092 applications trying to use the same file name namespace are cooperating on the use of files after 

28093 they have been created. 

28094 FUTURE DIRECTIONS 

28095 None. 
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28096 SEE ALSO 

28097 test, Section 2.7 on page 60 

28098 CHANGE HISTORY 

28099 First released in Issue 4. 
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28100 NAME 

28101 pax — portable archive interchange 

28102 SYNOPSIS 

28103 pax [—cdnv] [—H | —L] [—f archive] [—s replstr ] . . . [pattern . . .] 

28104 pax — r [—cdiknuv] [—H | —L] [—f archive] [—o options] . . . [—p string] . . . 

28105 [—s replstr] . . . [pattern . . .] 

28106 pax —w[—dituvX] [—H | —L ] [—b blocksize] [[—a] [—f archive] [—o options] . . . 

28107 [—s replstr] . . . [—x format] [file. . . ] 

28108 pax —r —w [—diklntuvX] [—H | —L] [— p string] . . . [—s replstr] . . . 

28109 [file...] directory 

28110 DESCRIPTION 


28111 Notes to Reviewers 

28112 This section with side shading will not appear in the final copy. - Ed. 

28113 pax has been extensively changed due to the merger with 2b. 

28114 The pax utility shall read, write, and write lists of the members of archive files and copy 

28115 directory hierarchies. A variety of archive formats shall be supported; see the -x format option. 


28116 

28117 

28118 

28119 

28120 
28121 
28122 


The action to be taken depends on the presence of the -r and -w options. The four combinations 
of -r and -w are referred to as the four modes of operation: list, read, write, and copy modes, 
corresponding respectively to the four forms shown in the SYNOPSIS section. I 

list In list mode (when neither -r nor -w are specified), pax shall write the names of I 

the members of the archive file read from the standard input, with path names I 
matching the specified patterns, to standard output. If a named file is of type 
directory, the file hierarchy rooted at that file shall be listed as well. I 


28123 

28124 

28125 

28126 
28127 


read In read mode (when -r is specified, but -w is not), pax shall extract the members of 

the archive file read from the standard input, with path names matching the 
specified patterns. If an extracted file is of type directory, the file hierarchy rooted 
at that file shall be extracted as well. The extracted files shall be created relative to 
the current file hierarchy. 


28128 The ownership, access, and modification times, and file mode of the restored files 

28129 are discussed under the -p option. 


28130 

28131 

28132 

28133 

28134 


write In write mode (when -w is specified, but -r is not), pax shall write the contents of I 

the file operands to the standard output in an archive format. If no file operands are I 
specified, a list of files to copy, one per line, shall be read from the standard input. 

A file of type directory shall include all of the files in the file hierarchy rooted at the 
file. 


28135 copy In copy mode (when both -r and -w are specified), pax shall copy the file operands I 

28136 to the destination directory. I 


28137 

28138 

28139 


If no file operands are specified, a list of files to copy, one per line, shall be read 
from the standard input. A file of type directory shall include all of the files in the 
file hierarchy rooted at the file. 


28140 

28141 

28142 

28143 


The effect of the copy shall be as if the copied files were written to an archive file I 
and then subsequently extracted, except that there may be hard links between the I 
original and the copied files. If the destination directory is a subdirectory of one of I 
the files to be copied, the results are unspecified. If the destination directory is a I 
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28168 
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file of a type not defined by the System Interfaces volume of IEEE Std. 1003.1-200x, I 
the results are implementation-dependent; otherwise, it shall be an error for the file I 
named by the directory operand not to exist, not be writable by the user, or not be a I 
file of type directory. I 

In read or copy modes, if intermediate directories are necessary to extract an archive member, 
pax shall perform actions equivalent to the mkdir() function defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x, called with the following arguments: 

• The intermediate directory used as the path argument 

• The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO as the mode 
argument 

If any specified pattern or file operands are not matched by at least one file or archive member, 
pax shall write a diagnostic message to standard error for each one that did not match and exit 
with a non-zero exit status. 

The archive formats described in the EXTENDED DESCRIPTION section shall be automatically I 
detected on input. The default output archive format shall be implementation-dependent. I 

A single archive can span multiple files. The pax utility shall determine, in an implementation- 
dependent manner, what file to read or write as the next file. 

If the selected archive format supports the specification of linked files, it shall be an error if these 
files cannot be linked when the archive is extracted. For archive formats that do not store file I 
contents with each name that causes a hard link, if the file that contains the data is not extracted I 
during this pax session, either the data shall be restored from the original file, or a diagnostic I 
message shall be displayed with the name of a file that can be used to extract the data. In I 
traversing directories, pax shall detect infinite loops; that is, entering a previously visited I 
directory that is an ancestor of the last file visited. When it detects an infinite loop, pax shall I 
write a diagnostic message to standard error and shall terminate. I 

OPTIONS 

The pax utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that the order of I 
presentation of the -o, -p, and -s options is significant. I 

The following options shall be supported: 

-r Read an archive file from standard input. 

-w Write files to the standard output in the specified archive format. 

-a Append files to the end of the archive. It is implementation-dependent which 

devices on the system support appending. Additional file formats unspecified by 
this volume of IEEE Std. 1003.1-200x may impose restrictions on appending. 

-b blocksize Block the output at a positive decimal integer number of bytes per write to the 

archive file. Devices and archive formats may impose restrictions on blocking. I 
Blocking shall be automatically determined on input. Portable applications shall I 
not specify a blocksize value larger than 32 256. Default blocking when creating I 
archives depends on the archive format. (See the -x option below.) 

-c Match all file or archive members except those specified by the pattern or file 

operands. 

-d Cause files of type directory being copied or archived or archive members of type I 

directory being extracted or listed to match only the file or archive member itself I 
and not the file hierarchy rooted at the file. I 
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28189 

28190 

-f archive 

Specify the path name of the input or output archive, overriding the default 
standard input (in list or read modes) or standard output (write mode). 

28191 

28192 

28193 

28194 

-H 

If a symbolic link referencing a file of type directory is specified on the command 
line, pax shall archive the file hierarchy rooted in the file referenced by the link, 
using the name of the link as the root of the file hierarchy. The default behavior 
shall be to archive the symbolic link itself. 

28195 

28196 

28197 

28198 

28199 

28200 

28201 

28202 

28203 

28204 

-i 

Interactively rename files or archive members. For each archive member matching 
a pattern operand or file matching a file operand, a prompt shall be written to the 
file /dev/tty. The prompt shall contain the name of the file or archive member, but 
the format is otherwise unspecified. A line shall then be read from /dev/tty. If this 
line is blank, the file or archive member shall be skipped. If this line consists of a 
single period, the file or archive member shall be processed with no modification 
to its name. Otherwise, its name shall be replaced with the contents of the line. The 
pax utility shall immediately exit with a non-zero exit status if end-of-file is 
encountered when reading a response or if /dev/tty cannot be opened for reading 
and writing. 

28205 

28206 


The results of extracting a hard link to a file that has been renamed during 
extraction are unspecified. 

28207 

-k 

Prevent the overwriting of existing files. 

28208 

28209 

-1 

(The letter ell.) In copy mode, hard links shall be made between the source and 
destination file hierarchies whenever possible. 

28210 

28211 

28212 

28213 

28214 

-L 

If a symbolic link referencing a file of type directory is specified on the command 
line or encountered during the traversal of a file hierarchy, pax shall archive the file 
hierarchy rooted in the file referenced by the link, using the name of the link as the 
root of the file hierarchy. The default behavior shall be to archive the symbolic link 
itself. 

28215 

28216 

28217 

-n 

Select the first archive member that matches each pattern operand. No more than 
one archive member shall be matched for each pattern (although members of type 
directory shall still match the file hierarchy rooted at that file). 

28218 

28219 

28220 

-o options 

Provide information to the implementation to modify the algorithm for extracting 
or writing files. The value of options shall consist of one or more comma-separated 
keywords of the form: 

28221 


keyword[ [:]= value] [, keyword [[ :]= value] , ... ] 

28222 

28223 

28224 


Some keywords apply only to certain file formats, as indicated with each 
description. Use of keywords that are inapplicable to the file format being 
processed produces undefined results. 

28225 

28226 

28227 


Keywords in the options argument shall be a string that would be a valid portable 
file name as described in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 3.282, Portable File Name Character Set. 

28228 

28229 


Note: Keywords are not expected to be file names, merely to follow the same 

character composition rules as portable file names. 

28230 

28231 

28232 

28233 

28234 


Keywords can be preceded with white space. The value field shall consist of zero or 
more characters; within value, the application shall precede any literal comma with 
a backslash, which shall be ignored, but preserves the comma as part of value. A 
comma as the final character, or a comma followed solely by white space as the 
final characters, in options shall be ignored. Multiple -o options can be specified; if 
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28235 

28236 

28237 

28238 

28239 

28240 

28241 

28242 

28243 

28244 

28245 

28246 

28247 

28248 

28249 

28250 

28251 

28252 

28253 

28254 

28255 

28256 

28257 

28258 

28259 

28260 
28261 
28262 

28263 

28264 

28265 

28266 

28267 

28268 

28269 

28270 

28271 

28272 

28273 

28274 

28275 

28276 

28277 

28278 
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keywords given to these multiple -o options conflict, the keywords and values 
appearing later in command line sequence shall take precedence and the earlier 
shall be silently ignored. The following keyword values of options shall be 
supported for the file formats as indicated: 

delet e=pattern 

(Applicable only to the -x pax format.) When used in write or copy mode, pax 
shall omit from extended header records that it produces any keywords 
matching the string pattern. When used in read or list mode, pax shall ignore 
any keywords matching the string pattern in the extended header records. In 
both cases, matching shall be performed using the pattern matching notation 
described in Section 2.13.1 on page 92 and Section 2.13.2 on page 93. For 
example: 

—o delete=security . * 

would suppress security-related information. See pax Extended Header on 
page 750 for extended header record keyword usage. 

exthdr.name=sfnny 

(Applicable only to the -x pax format.) This keyword allows user control over 
the name that is written into the ustar header blocks for the extended header 
produced under the circumstances described in pax Header Block on page 
749. The name shall be the contents of string, after the following character 
substitutions have been made: 


string 

Includes: 

Replaced By: 

%d 

The directory name of the file, equivalent to the result of the 


dirname utility on the translated path name. 

%f 

The file name of the file, equivalent to the result of the basename 


utility on the translated path name. 

"o "o 

A ' %' character. 


Any other ' %' characters in string produce undefined results. 

If no -o exthdr.name=sfnny is specified, pax shall use the following default 
value: 


%d/PaxHeaders/%f 

globexthdr.name=sfr/ny 

(Applicable only to the -x pax format.) When used in write or copy mode with 
the appropriate options, pax creates global extended header records with ustar 
header blocks that will be treated as regular files by previous versions of pax. 
This keyword allows user control over the name that is written into the ustar 
header blocks for global extended header records. The name shall be the 
contents of string, after the following character substitutions have been made: 


string 

Includes: 

Replaced By: 

%n 

An integer that represents the sequence number of the global 


extended header record in the archive, starting at 1. 

"6 "6 

A ' %' character. 
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28280 
28281 

28282 

28283 

28284 

28285 

28286 

28287 

28288 

28289 

28290 

28291 

28292 

28293 

28294 

28295 

28296 

28297 

28298 

28299 

28300 

28301 

28302 

28303 

28304 

28305 

28306 

28307 

28308 

28309 

28310 

28311 

28312 

28313 

28314 

28315 

28316 

28317 

28318 

28319 

28320 

28321 

28322 

28323 

28324 


Any other ' %' characters in string produce undefined results. 

If no -o globexthdr.name=sfn/iy is specified, pax shall use the following 
default value: 

$TMPDIR/GlobalHead.%n 

where $TMPDIR represents the value of the TMPDIR environment variable. If 
TMPDIR is not set, pax shall use /tmp. 

invalid=flcfion 

(Applicable only to the -x pax format.) This keyword allows user control over 
the action pax takes upon encountering values in an extended header record 
that, in read or copy mode, are invalid in the destination hierarchy or, in list 
mode, cannot be written in the codeset and current locale of the 
implementation. The following are invalid values that shall be recognized by 
pax: 

— In read or copy mode, a file name or link name that contains character 
encodings invalid in the destination hierarchy. (For example, the name 
may contain embedded NULs.) 

— In read or copy mode, a file name or link name that is longer than the 
maximum allowed in the destination hierarchy (for either a path name 
component or the entire path name). 

— In list mode, any character string value (file name, link name, user name, 
and so on) that cannot be written in the codeset and current locale of the 
implementation. 

The following mutually-exclusive values of the action argument are 
supported: 

bypass In read or copy mode, pax shall bypass the file, causing no 
change to the destination hierarchy. In list mode, pax shall write 
all requested valid values for the file, but its method for writing 
invalid values is unspecified. 

rename In read or copy mode, pax shall act as if the -i option were in 
effect for each file with invalid file name or link name values, 
allowing the user to provide a replacement name interactively. 
In list mode, pax shall behave identically to the bypass action. 

UTF-8 When used in read, copy, or list mode and a file name, link 

name, owner name, or any other field in an extended header 
record cannot be translated from the pax UTF-8 codeset format 
to the codeset and current locale of the implementation, pax 
shall use the actual UTF-8 encoding for the name. 

write In read or copy mode, pax shall write the file, translating or 

truncating the name, regardless of whether this may overwrite 
an existing file with a valid name. In list mode, pax shall behave 
identically to the bypass action. 

If no -o invalid= option is specified, pax shall act as if 
-oinvalid=bypass were specified. Any overwriting of existing 
files that may be allowed by the -oinvalid= actions shall be 
subject to permission (-p) and modification time (-u) 
restrictions, and shall be suppressed if the -k option is also 
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specified. 

linkdata (Applicable only to the -x pax format.) In write mode, pax shall 
write the contents of a file to the archive even when that file is 
merely a hard link to a file whose contents have already been 
written to the archive. 

listopt =format 

This keyword specifies the output format of the table of contents produced 
when the -v option is specified in list mode. See List Mode Format 
Specifications on page 745. To avoid ambiguity, the listopt =format shall be 
the only or final keyword =value pair in a -o option-argument; all characters in 
the remainder of the option-argument shall be considered part of the format 
string. When multiple -olistopt =format options are specified, the format 
strings shall be considered a single, concatenated string, evaluated in 
command line order. 

times 

(Applicable only to the -x pax format.) When used in write or copy mode, pax 
shall include atime, ctime, and mtime extended header records for each file. 
See pax Extended Header File Times on page 753. 

In addition to these keywords, if the -x pax format is specified, any of the 
keywords and values defined in pax Extended Header on page 750, including 
implementation extensions, can be used in -o option-arguments, in either of two 
modes: 

keyword =value 

When used in write or copy mode, these keyword/value pairs shall be 
included at the beginning of the archive as typeflag g global extended header 
records. When used in read or list mode, these keyword/value pairs shall act 
as if they had been at the beginning of the archive as typeflag g global 
extended header records. 

keyword:=z;flZne 

When used in write or copy mode, these keyword/value pairs shall be 
included as records at the beginning of a typeflag x extended header for each 
file. (This is equivalent to the equal-sign form except that it creates no 
typeflag g global extended header records.) When used in read or list mode, 
these keyword/value pairs shall act as if they were included as records at the 
end of each extended header; thus, they shall override any global or file- 
specific extended header record keywords of the same names. For example, in 
the command: 

pax —r —o " 
gname:=mygroup, 

" <archive 

the group name will be forced to a new value for all files read from the 
archive. 

The precedences of -o keywords over various fields in the archive are described in 

pax Extended Header Keyword Precedence on page 752. 

-p string Specify one or more file characteristic options (privileges). The string option- 
argument shall be a string specifying file characteristics to be retained or discarded 
on extraction. The string shall consist of the specification characters a, e, m, o, and 
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p. Other implementation-dependent characters can be included. Multiple I 
characteristics can be concatenated within the same string and multiple -p options 
can be specified. The meaning of the specification characters are as follows: 

a Do not preserve file access times. 

e Preserve the user ID, group ID, file mode bits (see the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 3.173, File Mode Bits), I 
access time, modification time, and any other implementation-dependent file I 
characteristics. 

m Do not preserve file modification times, 
o Preserve the user ID and group ID. 

p Preserve the file mode bits. Other implementation-dependent file mode I 
attributes may be preserved. 

In the preceding list, "preserve" indicates that an attribute stored in the archive 
shall be given to the extracted file, subject to the permissions of the invoking I 
process. The access and modification times of the file shall be preserved unless I 
otherwise specified with the -p option or not stored in the archive. All attributes I 
that are not preserved shall be determined as part of the normal file creation action I 
(see Section 1.7.1.4 on page 11). I 

If neither the e nor the o specification character is specified, or the user ID and 
group ID are not preserved for any reason, pax shall not set the S_ISUID and 
S_ISGID bits of the file mode. 

If the preservation of any of these items fails for any reason, pax shall write a I 
diagnostic message to standard error. Failure to preserve these items shall affect I 
the final exit status, but shall not cause the extracted file to be deleted. I 

If file characteristic letters in any of the string option-arguments are duplicated or I 
conflict with each other, the ones given last shall take precedence. For example, if 
-p eme is specified, file modification times are preserved. 

-s replstr Modify file or archive member names named by pattern or file operands according 
to the substitution expression replstr, using the syntax of the ed utility. The 
concepts of "address" and "line" are meaningless in the context of the pax utility, I 
and shall not be supplied. The format shall be: I 

— s /old/new/[ gp] 

where as in ed, old is a basic regular expression and new can contain an ampersand, 

' \n' (where n is a digit), backreferences, or subexpression matching. The old I 
string also shall be permitted to contain <newline> characters. 

Any non-null character can be used as a delimiter (' /' shown here). Multiple -s 
expressions can be specified; the expressions shall be applied in the order 
specified, terminating with the first successful substitution. The optional trailing 
' q' is as defined in the ed utility. The optional trailing ' p' shall cause successful 
substitutions to be written to standard error. File or archive member names that 
substitute to the empty string shall be ignored when reading and writing archives. 

-t Cause the access times of the archived files to be the same as they were before 

being read by pax. 

-u Ignore files that are older (having a less recent file modification time) than a pre¬ 

existing file or archive member with the same name. In read mode, an archive 
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member with the same name as a file in the file system shall be extracted if the 
archive member is newer than the file. In write mode, an archive file member with 
the same name as a file in the file system shall be superseded if the file is newer 
than the archive member. If -a is also specified, this is accomplished by appending I 
to the archive; otherwise, it is unspecified whether this is accomplished by actual I 
replacement in the archive or by appending to the archive. In copy mode, the file in 
the destination hierarchy shall be replaced by the file in the source hierarchy or by 
a link to the file in the source hierarchy if the file in the source hierarchy is newer. 

-v In list mode, produce a verbose table of contents (see the STDOUT section). 

Otherwise, write archive member path names to standard error (see the STDERR 
section). 

-xformat Specify the output archive format. The pax utility shall support the following I 
formats: I 

cpio The cpio interchange format; see the EXTENDED DESCRIPTION I 

section. The default blocksize for this format for character special 
archive files shall be 5120. Implementations shall support all 
blocksize values less than or equal to 32 256 that are multiples of 512. I 

pax The pax interchange format; see the EXTENDED DESCRIPTION I 

section. The default blocksize for this format for character special I 
archive files shall be 5120. Implementations shall support all I 
blocksize values less than or equal to 32 256 that are multiples of 512. I 

ustar The tar interchange format; see the EXTENDED DESCRIPTION I 

section. The default blocksize for this format for character special 
archive files shall be 10240. Implementations shall support all I 
blocksize values less than or equal to 32 256 that are multiples of 512. 

Implementation-dependent formats shall specify a default block size as well as any 
other block sizes supported for character special archive files. 

Any attempt to append to an archive file in a format different from the existing 
archive format shall cause pax to exit immediately with a non-zero exit status. I 

In copy mode, if no -x format is specified, pax shall behave as if -xpax were I 
specified. I 

-X When traversing the file hierarchy specified by a path name, pax shall not descend 

into directories that have a different device ID ( st_dev ; see the System Interfaces 
volume of IEEE Std. 1003.1-200x, stat ()). 

The options that operate on the names of files or archive members (-c, -i, -n, -s, -u, and -v) 
shall interact as follows. In read mode, the archive members shall be selected based on the user- 
specified pattern operands as modified by the -c, -n, and -u options. Then, any -s and -i options 
shall modify, in that order, the names of the selected files. The -v option shall write names 
resulting from these modifications. 

In write mode, the files shall be selected based on the user-specified path names as modified by I 
the -n and -u options. Then, any -s and -i options shall modify, in that order, the names of I 
these selected files. The -v option shall write names resulting from these modifications. I 

If both the -u and -n options are specified, pax shall not consider a file selected unless it is newer 
than the file to which it is compared. I 
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List Mode Format Specifications I 

In list mode with the -o listopt =format option, the format argument shall be applied for each 
selected file. The pax utility shall append a <newline> character to the listopt output for each 
selected file. The format argument shall be used as the format string described in the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation, with the 
exceptions 1. through 5. defined in the EXTENDED DESCRIPTION section of printf, plus the 
following exceptions: 

6. The sequence ( keyzvord ) can occur before a format conversion specifier. The conversion 
argument is defined by the value of keyzvord. The implementation shall support the 
following keywords: 

— Any of the Field Name entries in Table 4-13 on page 753 and Table 4-15 on page 757. The 
implementation may support the cpio keywords without the leading c_ in addition to the I 
form required by Table 4-16 on page 758. 

— Any keyword defined for the extended header in pax Extended Header on page 750. 

— Any keyword provided as an implementation-dependent extension within the extended 
header defined in pax Extended Header on page 750. 

For example, the sequence " % (charset) s " is the string value of the name of the character 
set in the extended header. 

The result of the keyword conversion argument shall be the value from the applicable 
header field or extended header, without any trailing NULs. 

All keyword values used as conversion arguments shall be translated from the UTF-8 
encoding to the character set appropriate for the local file system, user database, and so on, 
as applicable. 

7. An additional conversion character, T, shall be used to specify time formats. The T 
conversion character can be preceded by the sequence (keyivord= subformat), where subformat 
is a date format as defined by date operands. The default keyzvord shall be mtime and the 
default subformat shall be: 

-sb "se -sH : -sM Y 

8. An additional conversion character, M, shall be used to specify the file mode string as 
defined in Is Standard Output. If ( keyzvord ) is omitted, the mode keyword shall be used. For 
example, %.1M writes the single character corresponding to the <entry type> field of the Is 
-1 command. 

9. An additional conversion character, D, shall be used to specify the device for block or 
special files, if applicable, in an implementation-dependent format. If not applicable, and 
(keyzvord) is specified, then this conversion shall be equivalent to %(keyzvord)\i. If not 
applicable, and ( keyzvord ) is omitted, then this conversion shall be equivalent to <space>. 

10. An additional conversion character, F, shall be used to specify a path name. The F 
conversion character can be preceded by a sequence of comma-separated keywords: 

(keyword [, keyword] ... ) 

The values for all the keywords that are non-null shall be concatenated together, each 
separated by a ' / ' ■ The default shall be (path) if the keyword path is defined; otherwise, 
the default shall be (prefix,name). 

11. An additional conversion character, L, shall be used to specify a symbolic line expansion. If 
the current file is a symbolic link, then %L shall expand to: 
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28505 "%s —> %s", <value of keyword>, <contents of link> 

28506 Otherwise, the %L conversion character shall be the equivalent of %F. 

28507 OPERANDS 

28508 The following operands shall be supported: 


28509 directory The destination directory path name for copy mode. 

28510 file A path name of a file to be copied or archived. 


28511 

28512 

28513 

28514 

28515 


pattern A pattern matching one or more path names of archive members. A pattern must 

be given in the name-generating notation of the pattern matching notation in 
Section 2.13 on page 92, including the file name expansion rules in Section 2.13.3 
on page 94. The default, if no pattern is specified, is to select all members in the 
archive. 


28516 STDIN 

28517 In write mode, the standard input shall be used only if no file operands are specified. It shall be a I 

28518 text file containing a list of path names, one per line, without leading or trailing <blank> I 

28519 characters. 


28520 In list and read modes, if -f is not specified, the standard input shall be an archive file. 

28521 Otherwise, the standard input shall not be used. 

28522 INPUT FILES 

28523 The input file named by the archive option-argument, or standard input when the archive is read 

28524 from there, shall be a file formatted according to one of the specifications in the EXTENDED 

28525 DESCRIPTION section or some other implementation-dependent format. 

28526 The file /dev/tty shall be used to write prompts and read responses. 


28527 ENVIRONMENT VARIABLES 

28528 The following environment variables shall affect the execution of pax: 


28529 

28530 

28531 

28532 

28533 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


28534 

28535 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


28536 

28537 

28538 

28539 

28540 

28541 


LCjCOLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements used in the pattern matching expressions for the 
pattern operand, the basic regular expression for the -s option, and the extended 
regular expression defined for the yesexpr locale keyword in the LC_MESSAGES 
category. 


28542 

28543 

28544 

28545 

28546 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the behavior of character classes used in the extended 
regular expression defined for the yesexpr locale keyword in the LC_MESSAGES 
category, and pattern matching. 


28547 LC_MESSAGES 

28548 Determine the locale for the processing of affirmative responses that should be 
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28549 used to affect the format and contents of diagnostic messages written to standard 

28550 error. 


28551 LC_TIME Determine the format and contents of date and time strings when the -v option is 

28552 specified. 

28553 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. I 

28554 TMPDIR Determine the path name that provides part of the default global extended header I 

28555 record file, as described for the -o globexthdr= keyword as described in the I 

28556 OPTIONS section. I 


28557 ASYNCHRONOUS EVENTS 

28558 Default. 


28559 STDOUT 

28560 In write mode, if -f is not specified, the standard output shall be the archive formatted 

28561 according to one of the specifications in the EXTENDED DESCRIPTION section, or some other 

28562 implementation-dependent format (see -x format). 

28563 In list mode, when the -olistopt =format has been specified, the selected archive members shall I 

28564 be written to standard output using the format described under List Mode Format I 

28565 Specifications on page 745. In list mode without the -olistopt=/bmwf option, the table of I 

28566 contents of the the selected archive members shall be written to standard output using the I 

28567 following format: I 

28568 "%s\n", <path name> 

28569 If the -v option is specified in list mode, the table of contents of the selected archive members 

28570 shall be written to standard output using the following formats. 

28571 For path names representing hard links to previous members of the archive: 

28572 "%sA==A%s\n", <ls —1 listing> , <linkname> 

28573 For all other path names: 

28574 "%s\n", <ls —1 listing> 

28575 where </s -1 listing> shall be the format specified by the Is utility with the -1 option. When I 

28576 writing path names in this format, it is unspecified what is written for fields for which the 

28577 underlying archive format does not have the correct information, although the correct number of 

28578 <blank> character-separated fields shall be written. 

28579 In list mode, standard output shall not be buffered more than a line at a time. 

28580 STDERR 

28581 If -v is specified in read, write, or copy modes, pax shall write the path names it processes to the 

28582 standard error output using the following format: 

28583 "%s\n", <path name> 

28584 These path names shall be written as soon as processing is begun on the file or archive member, 

28585 and shall be flushed to standard error. The trailing <newline> character, which shall not be 

28586 buffered, is written when the file has been read or written. 

28587 If the -s option is specified, and the replacement string has a trailing ' p', substitutions shall be 

28588 written to standard error in the following format: 

28589 "%sA>>A%s\n", <original path name>, <new path name> 
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In all operating modes of pax, optional messages of unspecified format concerning the input 
archive format and volume number, the number of files, blocks, volumes, and media parts as 
well as other diagnostic messages may be written to standard error. 

In all formats, for both standard output and standard error, it is unspecified how non-printable 
characters in path names or link names are written. 

When pax is in read mode or list mode, using the -xpax archive format, and a file name, link 
name, owner name, or any other field in an extended header record cannot be translated from 
the pax UTF-8 codeset format to the codeset and current locale of the implementation, pax shall 
write a diagnostic message to standard error, shall process the file as described for the -o 
invalid=option, and then shall process the next file in the archive. 

OUTPUT FILES 

In read mode, the extracted output files shall be of the archived file type. In copy mode, the 
copied output files shall be the type of the file being copied. In either mode, existing files in the 
destination hierarchy shall be overwritten only when all permission (-p), modification time (-u), 
and invalid-value (-oinvalid=) tests allow it. 

In write mode, the output file named by the -f option-argument shall be a file formatted 
according to one of the specifications in the EXTENDED DESCRIPTION section, or some other 
implementation-dependent format. 

EXTENDED DESCRIPTION 

pax Interchange Format 

A pax archive tape or file produced in the -xpax format shall contain a series of blocks. The 
physical layout of the archive shall be identical to the ustar format described in ustar 
Interchange Format on page 753. Each file archived shall be represented by the following 
sequence: 

• An optional header block with extended header records. This header block is of the form 
described in pax Header Block on page 749, with a typeflag value of x or g. The extended 
header records, described in pax Extended Header on page 750, are included as the data for 
this header block. 

• A header block that describes the file. Any fields in the preceding optional extended header 
override the associated fields in this header block for this file. 

• Zero or more blocks that contain the contents of the file. 

At the end of the archive file there shall be two 512-byte blocks filled with binary zeroes, 
interpreted as an end-of-archive indicator. 

A schematic of an example archive with global extended header records and two actual files is 
shown in Figure 4-1 on page 749. In the example, the second file in the archive has no extended 
header preceding it, presumably because it has no need for extended attributes. 
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us tar Header [typeflag=g] 


Global Extended Header Data 


ustar Header [typeflag=x] 


Extended Header Data 


ustar Header [typeflag=0] 


Data for File 1 


ustar Header [typeflag=0] 


Data for File 2 


Block of binary zeroes 


Block of binary zeroes 


Global Extended Header 


File 1: Extended Header is 
included 


File 2: No Extended Header is 
included 


End of Archive Indicator 


Figure 4-1 pax Format Archive Example 

pax Header Block 

The pax header block shall be identical to the ustar header block described in ustar Interchange 
Format on page 753, except that two additional typeflag values are defined: 

x Represents extended header records for the following file in the archive (which shall have 
its own ustar header block). The format of these extended header records shall be as 
described in pax Extended Header on page 750. 

g Represents global extended header records for the following files in the archive. The format 
of these extended header records shall be as described in pax Extended Header on page 750. 
Each value shall affect all subsequent files that do not override that value in their own 
extended header record and until another global extended header record is reached that 
provides another value for the same field. The typeflag g global headers should not be used 
with interchange media that could suffer partial data loss in transporting the archive. 

For both of these types, the size field shall be the size of the extended header records in octets. 
The other fields in the header block are not meaningful to this version of the pax utility. 
However, if this archive is read by a pax utility conforming to a previous version of 
IEEE Std. 1003.1-200x, the header block fields are used to create a regular file that contains the 
extended header records as data. Therefore, header block field values should be selected to 
provide reasonable file access to this regular file. 

A further difference from the ustar header block is that data blocks for files of typeflag 1 (hard 
link) may be included, which means that the size field may be greater than zero. Archives 
created by pax -o linkdata shall include these data blocks with the hard links. 
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pax Extended Header 

A pax extended header contains values that are inappropriate for the ustar header block because 
of limitations in that format: fields requiring a character encoding other than that described in 
the ISO/IEC 646:1991 standard, fields representing file attributes not described in the ustar 
header, and fields whose format or length do not fit the requirements of the ustar header. The 
values in an extended header add attributes to the following file (or files; see the description of 
the typeflag g header block) or override values in the following header block(s), as indicated in 
the following list of keywords. 

An extended header shall consist of one or more records, each constructed as follows: 

"%d %s=%s\n", <length>, <keyword>, <value> 

The extended header records shall be encoded according to the ISO/IEC 10646-1:1993 standard 
(UTF-8). The <length> field, <blank> character, equals sign, and <newline> character shown 
shall be limited to the portable character set, as encoded in UTF-8. The <keyword> and <value> 
fields can be any UTF-8 characters. The <length> field shall be the decimal length of the extended 
header record in octets, including the trailing <newline> character. 

The <keyword> field shall be one of the entries from the following list or a keyword provided as 
an implementation extension. Keywords consisting entirely of lowercase letters, digits, and 
periods are reserved for future standardization. A keyword shall not include an equals sign. (In 
the following list, the notations "file(s)" or "block(s)" is used to acknowledge that a keyword 
affects the following single file after a typeflag x extended header, but possibly multiple files after 
typeflag g. Any requirements in the list for pax to include a record when in write or copy mode 
shall apply only when such a record has not already been provided through the use of the -o 
option. When used in copy mode, pax shall behave as if an archive had been created with 
applicable extended header records and then extracted.) 

atime The file access time for the following file(s), equivalent to the value of the st_atime 

member of the stat structure for a file, as described by the stat() function. The 
access time shall be restored if the process has the appropriate privilege required 
to do so. The format of the <value> shall be as described in pax Extended Header 
File Times on page 753. 

charset The name of the character set used to encode the data in the following file(s). The 
entries in the following table are defined to refer to known standards; additional 
names may be agreed on between the originator and recipient. 


<value> 

Formal Standard 

ISO-IRA64 6A1990 

ISO-IRA8859A1A1987 

ISO-IRA8859A2A1987 

ISO-IRA10646A1993 

ISO-IRA10646A1993AUTF-8 

BINARY 

ISO/IEC 646:1990 

ISO/IEC 8859-1:1987 

ISO/IEC 8859-2:1987 

ISO/IEC 10646:1993 

ISO/IEC 10646, UTF-8 encoding 
None. 


The encoding is included in an extended header for information only; when pax is 
used as described in IEEE Std. 1003.1-200x, it shall not translate the file data into 
any other encoding. The BINARY entry indicates unencoded binary data. 

When used in write or copy mode, it is implementation-dependent whether pax 
includes a charset extended header record for a file. 

comment A series of characters used as a comment. All characters in the <value> field shall 
be ignored by pax. 
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ctime 


gid 


gname 


linkpath 


mtime 


path 


The file creation time for the following file(s), equivalent to the value of the 
stjctime member of the stat structure for a file, as described by the stat( ) function. 
The creation time shall be restored if the process has the appropriate privilege 
required to do so. The format of the <value> shall be as described in pax Extended 
Header File Times on page 753. 

The group ID of the group that owns the file, expressed as a decimal number using 
digits from the ISO/IEC 646:1991 standard. This record shall override the gid field 
in the following header block(s). When used in write or copy mode, pax shall 
include a gid extended header record for each file whose group ID is greater than 
99999999. 

The group of the file(s), formatted as a group name in the group database. This 
record shall override the gid and gname fields in the following header block(s), and 
any gid extended header record. When used in read, copy, or list mode, pax shall 
translate the name from the UTF-8 encoding in the header record to the character 
set appropriate for the group database on the receiving system. If any of the UTF-8 
characters cannot be translated, and if the -oinvalid= UTF-8 option is not 
specified, the results are implementation-dependent. When used in write or copy 
mode, pax shall include a gname extended header record for each file whose group 
name cannot be represented entirely with the letters and digits of the portable 
character set. 

The path name of a link being created to another file, of any type, previously 
archived. This record shall override the linkname field in the following ustar header 
block(s). The following ustar header block shall determine the type of link created. 
If typeflag of the following header block is 1, it shall be a hard link. If typeflag is 2, it 
shall be a symbolic link and the linkpath value shall be the contents of the 
symbolic link. The pax utility shall translate the name of the link (contents of the 
symbolic link) from the UTF-8 encoding to the character set appropriate for the 
local file system. When used in write or copy mode, pax shall include a linkpath 
extended header record for each link whose path name cannot be represented 
entirely with the members of the portable character set other than NUL. 

The file modification time of the following file(s), equivalent to the value of the 
stjntime member of the stat structure for a file, as described in the stat( ) function. 
This record shall override the mtime field in the following header block(s). The 
modification time shall be restored if the process has the appropriate privilege 
required to do so. The format of the <value> shall be as described in pax Extended 
Header File Times on page 753. 

The path name of the following file(s). This record shall override the name and 
prefix fields in the following header block(s). The pax utility shall translate the path 
name of the file from the UTF-8 encoding to the character set appropriate for the 
local file system. 

When used in write or copy mode, pax shall include a path extended header record 
for each file whose path name cannot be represented entirely with the members of 
the portable character set other than NUL. 


realtime.am/ The keywords prefixed by "realtime." are reserved for future standardization. 


security .any The keywords prefixed by "security." are reserved for future standardization. 


size The size of the file in octets, expressed as a decimal number using digits from the 

ISO/IEC 646:1991 standard. This record shall override the size field in the 
following header block(s). When used in write or copy mode, pax shall include a 
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28744 

28745 

28746 
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28750 

28751 
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28756 

28757 

28758 

28759 
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28764 

28765 

28766 

28767 

28768 

28769 

28770 

28771 

28772 

28773 

28774 

28775 

28776 

28777 

28778 

28779 

28780 

28781 

28782 


size extended header record for each file with a size value greater than 
999999999999 

uid The user ID of the file owner, expressed as a decimal number using digits from the 

ISO/IEC 646:1991 standard. This record shall override the uid field in the 
following header block(s). When used in write or copy mode, pax shall include a 
uid extended header record for each file whose owner ID is greater than 99 999 999. 

uname The owner of the following file(s), formatted as a user name in the user database. 

This record shall override the irid and uname fields in the following header block(s), 
and any uid extended header record. When used in read, copy, or list mode, pax 
shall translate the name from the UTF-8 encoding in the header record to the 
character set appropriate for the user database on the receiving system. If any of 
the UTF-8 characters cannot be translated, and if the -oinvalid= UTF-8 option is 
not specified, the results are implementation-dependent. When used in write or 
copy mode, pax shall include a uname extended header record for each file whose 
user name cannot be represented entirely with the letters and digits of the portable 
character set. 

If the <value> field is zero length, it shall delete any header block field, previously entered 
extended header value, or global extended header value of the same name. 

If a keyword in an extended header record (or in a -o option-argument) overrides or deletes a 
corresponding field in the ustar header block, pax shall ignore the contents of that header block 
field. 

Unlike the ustar header block fields, NULs shall not delimit <value> s; all characters within the 
<value> field shall be considered data for the field. None of the length limitations of the ustar 
header block fields in Table 4-13 on page 753 shall apply to the extended header records. 

pax Extended Header Keyword Precedence 

This section describes the precedence in which the various header records and fields and 
command line options are selected to apply to a file in the archive. When pax is used in read or 
list modes, it shall determine a file attribute in the following sequence: 

1 . 

2 . 

3. 

4. 

5. 

6 . 

7. 


If -ode 1 ete=keyword-prefix is used, the affected attributes shall be determined from step 7., 
if applicable, or ignored otherwise. 

If -okeyzvord := is used, the affected attributes shall be ignored. 

If -o keyword :=value is used, the affected attribute shall be assigned the value. 

If there is a typeflag x extended header record, the affected attribute shall be assigned the 
<value>. When extended header records conflict, the last one given in the header shall take 
precedence. 

If -o keyword=value is used, the affected attribute shall be assigned the value. 

If there is a typeflag g global extended header record, the affected attribute shall be 
assigned the <value>. When global extended header records conflict, the last one given in 
the global header shall take precedence. 

Otherwise, the attribute shall be determined from the ustar header block. 


752 


Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


pax 


28783 

28784 

28785 

28786 

28787 

28788 

28789 

28790 

28791 

28792 

28793 

28794 

28795 

28796 

28797 

28798 

28799 

28800 
28801 

28802 

28803 

28804 

28805 

28806 

28807 

28808 

28809 

28810 
28811 
28812 

28813 

28814 

28815 

28816 

28817 

28818 

28819 

28820 
28821 
28822 

28823 

28824 

28825 

28826 

28827 

28828 
28829 


pax Extended Header File Times 

The pax utility shall write atime and ctime records for each file in write or copy modes only if 
the -otimes option is specified; pax shall write a mtime record for each file in write or copy 
modes if the file system of the underlying implementation supports time granularities smaller 
than that required by the ustar header block described in ustar Interchange Format. All of these 
time records shall be formatted as a decimal representation of the time in seconds since the 
Epoch. If a period (' .') decimal point character is present, the digits to the right of the point 
shall represent the units of a subsecond timing granularity, where the first digit is tenths of a 
second and each subsequent digit is a tenth of the previous digit. Implementations may ignore 
any portion of the subsecond digits for which they do not support the necessary timing 
granularity; they shall not perform any rounding operation. 

ustar Interchange Format 

A ustar archive tape or file shall contain a series of blocks. Each block shall be a fixed-size block 
of 512 octets (see below). Although this format may be thought of as being stored on 9-track 
industry-standard 12.7mm (0.5in) magnetic tape, other types of transportable media are not 
excluded. Each file archived shall be represented by a header block that describes the file, 
followed by zero or more blocks that give the contents of the file. At the end of the archive file 
there shall be two 512-octet blocks filled with binary zeros, interpreted as an end-of-archive 
indicator. 

The blocks may be grouped for physical I/O operations, as described under the -b blocksize and 
-x ustar options. Each group of blocks may be written with a single operation equivalent to the 
ivrite( ) function. On magnetic tape, the result of this write shall be a single tape record. The last 
group of blocks always shall be at the full size, so blocks after the two zero blocks may contain 
undefined data. 

The header block shall be structured as shown in the following table. All lengths and offsets are 
in decimal. 


Table 4-13 ustar Header Block 


Field Name 

Octet Offset 

Fength (in Octets) 

name 

0 

100 

mode 

100 

8 

uid 

108 

8 

gid 

116 

8 

size 

124 

12 

mtime 

136 

12 

chksum 

148 

8 

typeflag 

156 

1 

linkname 

157 

100 

magic 

257 

6 

version 

263 

2 

uname 

265 

32 

gname 

297 

32 

devmajor 

329 

8 

devminor 

337 

8 

prefix 

345 

155 


All characters in the header block shall be represented in the coded character set of the I 
ISO/IEC 646:1991 standard. For maximum portability between implementations, names should 
be selected from characters represented by the portable file name character set as octets with the 
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28830 most significant bit zero. If an implementation supports the use of characters outside of slash I 

28831 and the portable file name character set in names for files, users, and groups, one or more I 

28832 implementation-dependent encodings of these characters shall be provided for interchange I 

28833 purposes. I 

28834 Notes to Reviewers I 

28835 This section ivith side shading will not appear in the final copy. - Ed. I 

28836 The following paragraph was in XCU and is not in 1003.2b I 

28837 However, the pax utility shall never create file names on the local system that cannot be accessed I 

28838 via the procedures described previously in this volume of IEEE Std. 1003.1-200x. If a file name is I 

28839 found on the medium that would create an invalid file name, it is implementation-dependent I 

28840 whether the data from the file is stored on the file hierarchy and under what name it is stored. I 

28841 The pax utility may choose to ignore these files as long as it produces an error indicating that the I 

28842 file is being ignored. 

28843 Each field within the header block is contiguous; that is, there is no padding used. Each character I 

28844 on the archive medium shall be stored contiguously. I 

28845 The fields magic, nname, and gname are character strings each terminated by a NUL character. 

28846 The fields name, linkname, and prefix are NUL-terminated character strings except when all 

28847 characters in the array contain non-NUL characters including the last character. The version field 

28848 is two octets containing the characters "00" (zero-zero). The typeflag contains a single character. 

28849 All other fields are leading zero-filled octal numbers using digits from the ISO/IEC 646:1991 

28850 standard IRV. Each numeric field is terminated by one or more <space> or NUL characters. 

28851 The name and the prefix fields shall produce the path name of the file. A new path name shall be I 

28852 formed, if prefix is not an empty string (its first character is not NUL), by concatenating prefix (up I 

28853 to the first NUL character), a slash character, and name; otherwise, name is used alone. In either 

28854 case, name is terminated at the first NUL character. If prefix begins with a NUL character, it shall I 

28855 be ignored. In this manner, path names of at most 256 characters can be supported. If a path I 

28856 name does not fit in the space provided, pax shall notify the user of the error, and shall not store I 

28857 any part of the file—header or data—on the medium. 

28858 The linkname field, described below, shall not use the prefix to produce a path name. As such, a I 

28859 linkname is limited to 100 characters. If the name does not fit in the space provided, pax shall 

28860 notify the user of the error, and shall not attempt to store the link on the medium. 

28861 The mode field provides 12 bits encoded in the ISO/IEC 646:1991 standard octal digit I 

28862 representation. The encoded bits shall represent the following values: I 


754 


Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


pax 


28863 

28864 

28865 

28866 

28867 

28868 

28869 

28870 

28871 

28872 

28873 

28874 

28875 

28876 

28877 

28878 

28879 

28880 
28881 

28882 

28883 

28884 

28885 

28886 

28887 

28888 

28889 

28890 

28891 

28892 

28893 

28894 

28895 

28896 

28897 

28898 

28899 

28900 

28901 

28902 

28903 

28904 

28905 

28906 

28907 

28908 

28909 

28910 


Table 4-14 ustar mode Field 


Bit Value 

IEEE Std. 1003.1-200x Bit 

Description 

04000 

S_ISUID 

Set UID on execution. 

02 000 

S_ISGID 

Set GID on execution. 

01000 

<reserved> 

Reserved for future standardization. 

00400 

S_IRUSR 

Read permission for file owner class. 

00200 

S_IWUSR 

Write permission for file owner class. 

00100 

S_IXUSR 

Execute/search permission for file owner class. 

00040 

S_IRGRP 

Read permission for file group class. 

00020 

S_IWGRP 

Write permission for file group class. 

00010 

S_IXGRP 

Execute /search permission for file group class. 

00004 

S_IROTH 

Read permission for file other class. 

00002 

S_IWOTH 

Write permission for file other class. 

00001 

S_IXOTH 

Execute /search permission for file other class. 


When appropriate privilege is required to set one of these mode bits, and the user restoring the I 
files from the archive does not have the appropriate privilege, the mode bits for which the user 
does not have appropriate privilege shall be ignored. Some of the mode bits in the archive I 
format are not mentioned elsewhere in this volume of IEEE Std. 1003.1-200x. If the 
implementation does not support those bits, they may be ignored. 

The idd and gid fields are the user and group ID of the owner and group of the file, respectively. 

The size field is the size of the file in octets. If the typeflag field is set to specify a file to be of type 
1 (a link) or 2 (reserved for symbolic links), the size field shall be specified as zero. If the typeflag 
field is set to specify a file of type 5 (directory), the size field shall be interpreted as described 
under the definition of that record type. No data blocks are stored for types 1, 2, or 5. If the 
typeflag field is set to 3 (character special file), 4 (block special file), or 6 (FIFO), the meaning of 
the size field is unspecified by this volume of IEEE Std. 1003.1-200x, and no data blocks shall be I 
stored on the medium. Additionally, for 6, the size field shall be ignored when reading. If the I 
typeflag field is set to any other value, the number of blocks written following the header shall be 
(size +511)/512, ignoring any fraction in the result of the division. 

The mtime field shall be the modification time of the file at the time it was archived. It is the I 
ISO/IEC 646:1991 standard representation of the octal value of the modification time obtained 
from the stat( ) function. I 

The chksum field shall be the ISO/IEC 646:1991 standard IRV representation of the octal value of I 
the simple sum of all octets in the header block. Each octet in the header shall be treated as an I 
unsigned value. These values shall be added to an unsigned integer, initialized to zero, the I 
precision of which is not less than 17 bits. When calculating the checksum, the chksum field is I 
treated as if it were all spaces. 

The typeflag field specifies the type of file archived. If a particular implementation does not 
recognize the type, or the user does not have appropriate privilege to create that type, the file 
shall be extracted as if it were a regular file if the file type is defined to have a meaning for the 
size field that could cause data blocks to be written on the medium (see the previous description 
for size). If conversion to a regular file occurs, the pax utility shall produce an error indicating 
that the conversion took place. All of the typeflag fields shall be coded in the ISO/IEC 646:1991 
standard IRV: 

0 Represents a regular file. For backward compatibility, a typeflag value of binary zero 

(' \ 0') should be recognized as meaning a regular file when extracting files from the 
archive. Archives written with this version of the archive file format create regular files 
with a typeflag value of the ISO/IEC 646:1991 standard IRV 'O'. 
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1 Represents a file linked to another file, of any type, previously archived. Such files are 
identified by each file having the same device and file serial number. The linked-to 
name is specified in the linkname field with a NUL-character terminator if it is less than 
100 octets in length. 

2 Represents a symbolic link. The contents of the symbolic link shall be stored in the 
linkname field. 

3, 4 Represent character special files and block special files respectively. In this case the 
devmajor and devminor fields shall contain information defining the device, the format 
of which is unspecified by this volume of IEEE Std. 1003.1-200x. Implementations may 
map the device specifications to their own local specification or may ignore the entry. 

5 Specifies a directory or subdirectory. On systems where disk allocation is performed on 
a directory basis, the size field shall contain the maximum number of octets (which may 
be rounded to the nearest disk block allocation unit) that the directory may hold. A size 
field of zero indicates no such limiting. Systems that do not support limiting in this 
manner should ignore the size field. 

6 Specifies a FIFO special file. Note that the archiving of a FIFO file archives the existence 
of this file and not its contents. 

7 Reserved to represent a file to which an implementation has associated some high- 
performance attribute. Implementations without such extensions should treat this file 
as a regular file (type 0). 

A-Z The letters 'A' to ' Z', inclusive, are reserved for custom implementations. All other 
values are reserved for future revisions of IEEE Std. 1003.1-200x. 

The magic field is the specification that this archive was output in this archive format. If this field 
contains ustar (the five characters from the ISO/IEC 646:1991 standard IRV shown followed by 
NUL), the nname and gname fields shall contain the ISO/IEC 646:1991 standard IRV 
representation of the owner and group of the file, respectively (truncated to fit, if necessary). 
When the file is restored by a privileged, protection-preserving version of the utility, the user 
and group databases shall be scanned for these names. If found, the user and group IDs 
contained within these files shall be used rather than the values contained within the uid and gid 
fields. 

cpio Interchange Format 

The octet-oriented cpio archive format shall be a series of entries, each comprising a header that 
describes the file, the name of the file, and then the contents of the file. 

An archive may be recorded as a series of fixed-size blocks of octets. This blocking shall be used 
only to make physical I/O more efficient. The last group of blocks shall be always at the full 
size. 

For the octet-oriented cpio archive format, the individual entry information shall be in the order 
indicated and described by the following table; see also the <cpio.h> header. 


756 


Technical Standard (2000) (Draft February 29, 2000) 





Utilities 


pax 


28949 

28950 

28951 

28952 

28953 

28954 

28955 

28956 

28957 

28958 

28959 

28960 

28961 

28962 

28963 

28964 

28965 


28966 

28967 

28968 

28969 

28970 

28971 

28972 

28973 

28974 

28975 

28976 

28977 

28978 


Table 4-15 Octet-Oriented cpio Archive Entry 


Header Field Name 

Length (in Octets) 

Interpreted as 

c_magic 

6 

Octal number 

c_dev 

6 

Octal number 

c_ino 

6 

Octal number 

cjnode 

6 

Octal number 

cjiid 

6 

Octal number 

C-gid 

6 

Octal number 

c_nlink 

6 

Octal number 

cjrdev 

6 

Octal number 

cjntime 

11 

Octal number 

c_namesize 

6 

Octal number 

cjilesize 

11 

Octal number 

File Name Field Name 

Length 

Interpreted as 

c_name 

c_namesize 

Path name string 

File Data Field Name 

Length 

Interpreted as 

cjiledata 

cjilesize 

Data 


cpio Header 

For each file in the archive, a header as defined previously shall be written. The information in 
the header fields is written as streams of the ISO/IEC 646:1991 standard characters interpreted 
as octal numbers. The octal numbers shall be extended to the necessary length by appending the 
ISO/IEC 646:1991 standard IRV zeros at the most-significant-digit end of the number; the result 
is written to the most-significant digit of the stream of octets first. The fields shall be interpreted 
as follows: 

c_magic 
c_dev, c_ino 


cjnode 


Identify the archive as being a transportable archive by containing the identifying 
value "070707". 

Contains values that uniquely identify the file within the archive (that is, no files 
contain the same pair of c_dev and cjno values unless they are links to the same 
file). The values shall be determined in an unspecified manner. 

Contains the file type and access permissions as defined in the following table. 
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28979 Table 4-16 Values for cpio cjnode Field 


28980 

File Permissions Name 

Value 

Indicates 

28981 

C_IRUSR 

000400 

Read by owner 

28982 

CJWUSR 

000200 

Write by owner 

28983 

C_IXUSR 

000100 

Execute by owner 

28984 

C_IRGRP 

000040 

Read by group 

28985 

C_IWGRP 

000020 

Write by group 

28986 

C_IXGRP 

000010 

Execute by group 

28987 

C_IROTH 

000004 

Read by others 

28988 

C_IWOTH 

000002 

Write by others 

28989 

C_IXOTH 

000001 

Execute by others 

28990 

C_ISUID 

004000 

Set uid 

28991 

CJSGID 

002 000 

Set gid 

28992 

C_ISVTX 

001000 

Reserved 

28993 

File Type Name 

Value 

Indicates 

28994 

CJSDIR 

040000 

Directory 

28995 

C_ISFIFO 

010000 

FIFO 

28996 

C_ISREG 

0100000 

Regular file 

28997 

C_ISBLK 

060000 

Block special file 

28998 

C_ISCHR 

020000 

Character special file 

28999 

C_ISCTG 

0110000 

Reserved 

29000 

C_ISLNK 

0120000 

Reserved 

29001 

CJSSOCK 

0140000 

Reserved 


29002 Directories, FIFOs, and regular files shall be supported on a system conforming to 

29003 this volume of IEEE Std. 1003.1-200x; additional values defined previously are 

29004 reserved for compatibility with existing systems. Additional file types may be 

29005 supported; however, such files should not be written to archives intended to be 

29006 transported to other systems. 

29007 c_uid Contains the user ID of the owner. 

29008 C-gid Contains the group ID of the group. 

29009 c_nlink Contains the number of links referencing the file at the time the archive was 

29010 created. 

29011 c_rdev Contains implementation-dependent information for character or block special 

29012 files. 

29013 cjntime Contains the latest time of modification of the file at the time the archive was 

29014 created. 

29015 c_namesize Contains the length of the path name, including the terminating NUL character. 

29016 cjilesize Contains the length of the file in octets. This shall be the length of the data section 

29017 following the header structure. 


758 


Technical Standard (2000) (Draft February 29, 2000) 





Utilities 


pax 


29018 cpio File Name 

29019 The c_name field shall contain the path name of the file. The length of this field in octets is the 

29020 value of c_namesize. 

29021 Notes to Reviewers 

29022 This section with side shading will not appear in the final copy. - Ed. 

29023 The following paragraph in XCU is not present in 1003.2b. Comments? 

29024 If a file name is found on the medium that would create an invalid path name, it is 

29025 implementation-dependent whether the data from the file is stored on the file hierarchy and 

29026 under what name it is stored. 

29027 All characters shall be represented in the ISO/IEC 646:1991 standard IRV. For maximum 

29028 portability between implementations, names should be selected from characters represented by 

29029 the portable file name character set as octets with the most significant bit zero. If an 

29030 implementation supports the use of characters outside the portable file name character set in 

29031 names for files, users, and groups, one or more implementation-dependent encodings of these 

29032 characters shall be provided for interchange purposes. 

29033 Notes to Reviewers 

29034 This section with side shading will not appear in the final copy. - Ed. 

29035 The next sentence is in XCU but not in 1003.2b 

29036 However, the pax utility shall never create file names on the local system that cannot be accessed 

29037 via the procedures described previously in this volume of IEEE Std. 1003.1-200x. If a file name is 

29038 found on the medium that would create an invalid file name, it is implementation-dependent 

29039 whether the data from the file is stored on the local file system and under what name it is stored. 

29040 The pax utility may choose to ignore these files as long as it produces an error indicating that the 

29041 file is being ignored. 

29042 cpio File Data 

29043 Following c_name, there shall be cjilesize octets of data. Interpretation of such data occurs in a 

29044 manner dependent on the file. If c_filesize is zero, no data shall be contained in cjiledata. 

29045 Notes to Reviewers 

29046 This section with side shading will not appear in the final copy. - Ed. 

29047 The following bullet items are in XCU but not in 1003.2b. Comments? 

29048 When restoring from an archive: 

29049 • If the user does not have the appropriate privilege to create a file of the specified type, pax 

29050 shall ignore the entry and write an error message to standard error. 

29051 • Only regular files have data to be restored. Presuming a regular file meets any selection 

29052 criteria that might be imposed on the format-reading utility by the user, such data shall be 

29053 restored. 

29054 • If a user does not have appropriate privilege to set a particular mode flag, the flag shall be 

29055 ignored. Some of the mode flags in the archive format are not mentioned elsewhere in this 

29056 volume of IEEE Std. 1003.1-200x. If the implementation does not support those flags, they 

29057 may be ignored. 
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cpio Special Entries I 

FIFO special files, directories, and the trailer shall be recorded with cjilesize equal to zero. For I 
other special files, cjilesize is unspecified by this volume of IEEE Std. 1003.1-200x. The header I 
for the next file entry in the archive shall be written directly after the last octet of the file entry I 
preceding it. A header denoting the file name TRAILER!!! indicates the end of the archive; the I 
contents of octets in the last block of the archive following such a header are undefined. I 

EXIT STATUS 

The following exit values shall be returned: 

0 All files were processed successfully. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If pax cannot create a file or a link when reading an archive or cannot find a file when writing an 
archive, or cannot preserve the user ID, group ID, or file mode when the -p option is specified, a 
diagnostic message shall be written to standard error and a non-zero exit status shall be 
returned, but processing shall continue. In the case where pax cannot create a link to a file, pax 
shall not, by default, create a second copy of the file. 

If the extraction of a file from an archive is prematurely terminated by a signal or error, pax may 
have only partially extracted the file or (if the -n option was not specified) may have extracted a 
file of the same name as that specified by the user, but which is not the file the user wanted. 
Additionally, the file modes of extracted directories may have additional bits from the S_IRWXU 
mask set as well as incorrect modification and access times. 

APPLICATION USAGE 

The -p (privileges) option was invented to reconcile differences between historical tar and cpio 
implementations. In particular, the two utilities use -m in diametrically opposed ways. The -p 
option also provides a consistent means of extending the ways in which future file attributes can 
be addressed, such as for enhanced security systems or high-performance files. Although it may 
seem complex, there are really two modes that are most commonly used: 

-p e "Preserve everything". This would be used by the historical superuser, someone with 
all the appropriate privileges, to preserve all aspects of the files as they are recorded in 
the archive. The e flag is the sum of o and p, and other implementation-dependent 
attributes. 

-p p "Preserve" the file mode bits. This would be used by the user with regular privileges 
who wished to preserve aspects of the file other than the ownership. The file times are 
preserved by default, but two other flags are offered to disable these and use the time 
of extraction. 

The one path name per line format of standard input precludes path names containing I 
<newline> characters. Although such path names violate the portable file name guidelines, they 
may exist and their presence may inhibit usage of pax within shell scripts. This problem is I 
inherited from historical archive programs. The problem can be avoided by listing file name I 
arguments on the command line instead of on standard input. I 

It is almost certain that appropriate privileges are required for pax to accomplish parts of this 
volume of IEEE Std. 1003.1-200x. Specifically, creating files of type block special or character 
special, restoring file access times unless the files are owned by the user (the -t option), or 
preserving file owner, group, and mode (the -p option) all probably require appropriate 
privileges. 


760 Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


pax 


29103 In read mode, implementations are permitted to overwrite files when the archive has multiple 

29104 members with the same name. This may fail if permissions on the first version of the file do not 

29105 permit it to be overwritten. 

29106 The cpio and ustar formats can only support files up to 8 gigabytes in size. I 

29107 EXAMPLES 

29108 The following command: 

29109 pax —w —f /dev/rmt/lm . 

29110 copies the contents of the current directory to tape drive 1, medium density (assuming historical I 

29111 System V device naming procedures. The historical BSD device name would be /dev/rmt9). I 

29112 The following commands: 

29113 mkdir newdir 

29114 pax — rw olddir newdir 

29115 copy the olddir directory hierarchy to neivdir. 

29116 pax -r —s ',7/*usr//*,,' -f a.pax 

29117 reads the archive a.pax, with all files rooted in /usr in the archive extracted relative to the current 

29118 directory. I 

29119 Using the option: I 

29120 —o listopt = "%M %(atime)T %(size)D % (name) s" I 

29121 overrides the default output description in Standard Output and instead writes: I 

29122 —rw—rw-Jan 12 15:53 1492 /usr/foo/bar I 

29123 Using the options: I 

29124 —o listopt = '%L\t% (size) D\n%. 7' \ I 

29125 — o listopt = ' (name) s\n% (ctime) T\n%T' I 

29126 overrides the default output description in Standard Output and instead writes: I 

29127 /usr/foo/bar —> /tmp 1492 I 

29128 /usr/fo I 

29129 Jan 12 1991 I 

29130 Jan 31 15:53 I 

29131 RATIONALE I 

29132 The pax utility was new, commissioned for the ISO POSIX-2:1993 standard. It represents a 

29133 peaceful compromise between advocates of the historical tar and cpio utilities. 

29134 A fundamental difference between cpio and tar was in the way directories were treated. The cpio I 

29135 utility did not treat directories differently from other files, and to select a directory and its 

29136 contents required that each file in the hierarchy be explicitly specified. For tar, a directory 

29137 matched every file in the file hierarchy it rooted. 

29138 The pax utility offers both interfaces; by default, directories map into the file hierarchy they root. 

29139 The -d option causes pax to skip any file not explicitly referenced, as cpio historically did. The tar I 

29140 -style behavior was chosen as the default because it was believed that this was the more 

29141 common usage and because tar is the more commonly available interface, as it was historically I 

29142 provided on both System V and BSD implementations. I 

29143 The data interchange format specification in this volume of IEEE Std. 1003.1-200x requires that 

29144 processes with "appropriate privileges" shall always restore the ownership and permissions of 
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extracted files exactly as archived. If viewed from the historic equivalence between superuser 
and "appropriate privileges", there are two problems with this requirement. First, users running 
as superusers may unknowingly set dangerous permissions on extracted files. Second, it is I 

needlessly limiting, in that superusers cannot extract files and own them as superuser unless the I 

archive was created by the superuser. (It should be noted that restoration of ownerships and 
permissions for the superuser, by default, is historical practice in cpio, but not in tar.) In order to 
avoid these two problems, the pax specification has an additional "privilege" mechanism, the -p 
option. Only a pax invocation with the privileges needed, and which has the -p option set using I 
the e specification character, has the "appropriate privilege" to restore full ownership and 
permission information. 

Note also that this volume of IEEE Std. 1003.1-200x requires that the file ownership and access 
permissions shall be set, on extraction, in the same fashion as the creat () function when provided I 
the mode stored in the archive. This means that the file creation mask of the user is applied to I 
the file permissions. I 

Users should note that directories may be created by pax while extracting files with permissions I 

that are different from those that existed at the time the archive was created. When extracting I 

sensitive information into a directory hierarchy that no longer exists, users are encouraged to set I 
their file creation mask appropriately to protect these files during extraction. I 

The table of contents output is written to standard output to facilitate pipeline processing. I 

The one path name per line format of standard input precludes path names containing I 
<newline> characters. Although such path names violate the portable file name guidelines, they I 
may exist and their presence may inhibit usage of pax within shell scripts. This problem is I 
inherited from historical archive programs. The problem can be avoided by listing file name I 
arguments on the command line instead of on standard input. I 

An early proposal had hard links displaying for all path names. This was removed because it I 

complicates the output of the case where -v is not specified and does not match historical cpio I 

usage. The hard-link information is available in the -v display. 

The archive formats inherited from the POSIX.1-1990 standard have certain restrictions that I 
have been brought along from historical usage. For example, there are restrictions on the length I 
of path names stored in the archive. When pax is used in copy( -rw) mode (copying directory I 
hierarchies), the ability to use extensions from the -xpax format overcomes these restrictions. I 

The default blocksize value of 5120 bytes for cpio was selected because it is one of the standard 
block-size values for cpio, set when the -B option is specified. (The other default block-size value 
for cpio is 512 bytes, and this was considered to be too small.) The default block value of 10 240 
bytes for tar was selected because that is the standard block-size value for BSD tar. The 
maximum block size of 32 256 bytes (2 15 -512 bytes) is the largest multiple of 512 bytes that fits 
into a signed 16-bit tape controller transfer register. There are known limitations in some 
historical systems that would prevent larger blocks from being accepted. Historical values were 
chosen to improve compatibility with historical scripts using dd or similar utilities to manipulate 
archives. Also, default block sizes for any file type other than character special file has been 
deleted from this volume of IEEE Std. 1003.1-200x as unimportant and not likely to affect the 
structure of the resulting archive. 

Implementations are permitted to modify the block-size value based on the archive format or I 

the device to which the archive is being written. This is to provide implementations with the I 

opportunity to take advantage of special types of devices, and it should not be used without a I 

great deal of consideration as it almost certainly decreases archive portability. 

The intended use of the -n option was to permit extraction of one or more files from the archive I 

without processing the entire archive. This was viewed by the standard developers as offering I 
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significant performance advantages over historical implementations. The -n option in early I 
proposals had three effects; the first was to cause special characters in patterns to not be treated 
specially. The second was to cause only the first file that matched a pattern to be extracted. The 
third was to cause pax to write a diagnostic message to standard error when no file was found 
matching a specified pattern. Only the second behavior is retained by this volume of I 
IEEE Std. 1003.1-200x, for many reasons. First, it is in general not acceptable for a single option to I 
have multiple effects. Second, the ability to make pattern matching characters act as normal 
characters is useful for parts of pax other than file extraction. Third, a finer degree of control over 
the special characters is useful because users may wish to normalize only a single special 
character in a single file name. Fourth, given a more general escape mechanism, the previous 
behavior of the -n option can be easily obtained using the -s option or a sed script. Finally, 
writing a diagnostic message when a pattern specified by the user is unmatched by any file is 
useful behavior in all cases. 

In this version, the -n was removed from the copy mode synopsis of pax; it is inapplicable I 
because there are no pattern operands specified in this mode. I 

There is another method than pax for copying subtrees in IEEE Std. 1003.1-200x described as part I 
of the cp utility. Both methods are historical practice: cp provides a simpler, more intuitive I 
interface, while pax offers a finer granularity of control. Each provides additional functionality to 
the other; in particular, pax maintains the hard-link structure of the hierarchy while cp does not. 

It is the intention of the standard developers that the results be similar (using appropriate option 
combinations in both utilities). The results are not required to be identical; there seemed 
insufficient gain to applications to balance the difficulty of implementations having to guarantee 
that the results would be exactly identical. 

A single archive may span more than one file. It is suggested that implementations provide I 
informative messages to the user on standard error whenever the archive file is changed. I 

The -d option (do not create intermediate directories not listed in the archive) found in early I 
proposals was originally provided as a complement to the historic -d option of cpio. It has been I 
deleted. 

The -s option in early proposals specified a subset of the substitution command from the ed I 
utility. As there was no reason for only a subset to be supported, the -s option is now 
compatible with the current ed specification. Since the delimiter can be any non-null character, 
the following usage with single spaces is valid: 

pax —s " foo bar " ... 

The -t option (specify an implementation-dependent identifier naming an input or output I 
device) found in early proposals has been deleted because it is not historical practice and is of I 
limited utility. In particular, historic versions of neither cpio nor tar had the concept of devices I 
that were not mapped into the file system; if the devices are mapped into the file system, the -f 
option is sufficient. 

The default behavior of pax with regard to file modification times is the same as historical I 
implementations of tar. It is not the historical behavior of cpio. 

Because the -i option uses /dev/tty, utilities without a controlling terminal are not able to use 
this option. 

The -y option, found in early proposals, has been deleted because a line containing a single 
period for the -i option has equivalent functionality. The special lines for the -i option (a single 
period and the empty line) are historical practice in cpio. 

In early drafts, an -echarmap option was included to increase portability of files between systems I 
using different coded character sets. This option was omitted because it was apparent that I 
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consensus could not be formed for it. In this version, the use of UTF-8 should be an adequate I 
substitute. I 

The -k option was added to address international concerns about the dangers involved in the 
character set transformations of -e (if the target character set were different than the source, the 
file names might be transformed into names matching existing files) and also was made more 
general to protect files transferred between file systems with different |NAME_MAX} values 
(truncating a file name on a smaller system might also inadvertently overwrite existing files). As 
stated, it prevents any overwriting, even if the target file is older than the source. This version I 
adds more granularity of options to solve this problem by introducing the -oinvalid= option— I 
specifically the UTF-8 action. (Note that an existing file that is named with a UTF-8 encoding is I 
still subject to overwriting in this case. The -k option closes that loophole.) I 

Some of the file characteristics referenced in this volume of IEEE Std. 1003.1-200x might not be I 
supported by some archive formats. For example, neither the tar nor cpio formats contain the file 
access time. For this reason, the e specification character has been provided, intended to cause all 
file characteristics specified in the archive to be retained. 

It is required that extracted directories, by default, have their access and modification times and 
permissions set to the values specified in the archive. This has obvious problems in that the 
directories are almost certainly modified after being extracted and that directory permissions 
may not permit file creation. One possible solution is to create directories with the mode 
specified in the archive, as modified by the umask of the user, with sufficient permissions to I 
allow file creation. After all files have been extracted, pax would then reset the access and 
modification times and permissions as necessary. I 

The list-mode formatting description borrows heavily from the one defined by the print/ utility. I 
However, since there is no separate operand list to get conversion arguments, the format was I 
extended to allow specifying the name of the conversion argument as part of the conversion I 
specification. I 

The T specifier allows time fields to be displayed in any of the date formats. Unlike the Is utility, I 
pax does not adjust the format when the date is less than six months in the past. This makes I 
parsing the output more predictable. I 

The D specifier handles the ability to display the major/minor or file size, as with Is, by using I 
%-8(size)D. I 

The L specifier handles the Is display for symbolic links. I 

Conversion specifiers were added to generate existing known types used for Is. I 

pax Interchange Format I 

The new POSIX data interchange format was developed primarily to satisfy international I 
concerns that the ustar and cpio formats did not provide for file, user, and group names encoded I 
in characters outside a subset of the ISO/IEC 646:1991 standard. The standard developers I 
realized that this new POSIX data interchange format should be very extensible because there I 
were other requirements they foresaw in the near future: I 

• Support international character encodings and locale information I 

• Support security information (ACLs, and so on) I 

• Support future file types, such as realtime or contiguous files I 

• Include data areas for implementation use I 
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• Support systems with words larger than 32 bits and timers with subsecond granularity 

The following were not goals for this format because these are better handled by separate 
utilities or are inappropriate for a portable format: 

• Encryption 

• Compression 

• Data translation between locales and codesets 

• inode storage 

The format chosen to support the goals is an extension of the ustar format. Of the two formats 
previously available, only the ustar format was selected for extensions because: 

• It was easier to extend in an upward-compatible way. It offered version flags and header 
block type fields with room for future standardization. The cpio format, while possessing a 
more flexible file naming methodology, could not be extended without breaking some 
theoretical implementation or using a dummy file name that could be a legitimate file name. 

• Industry experience since the original "tar wars" fought in developing the ISO POSIX-1 
standard has clearly been in favor of the ustar format, which is generally the default output 
format selected for pax implementations on new systems. 

The new format was designed with one additional goal in mind: reasonable behavior when an 
older tar or pax utility happened to read an archive. Since the POSIX.1-1990 standard mandated 
that a "format-reading utility" had to treat unrecognized typeflag values as regular files, this 
allowed the format to include all the extended information in a pseudo-regular file that preceded 
each real file. An option is given that allows the archive creator to set up reasonable names for 
these files on the older systems. Also, the normative text suggests that reasonable file access 
values be used for this ustar header block. Making these header files inaccessible for convenient 
reading and deleting would not be reasonable. File permissions of 600 or 700 are suggested. 

The ustar typeflag field was used to accommodate the additional functionality of the new format 
rather than magic or version because the POSIX.1-1990 standard (and, by reference, the previous 
version of pax), mandated the behavior of the format-reading utility when it encountered an 
unknown typeflag, but was silent about the other two fields. 

Early proposals of the first revision to IEEE Std. 1003.1-200x contained a proposed archive 
format that was based on compatibility with the standard for tape files (ISO 1001, similar to the 
format used historically on many mainframes and minicomputers). This format was overly 
complex and required considerable overhead in volume and header records. Furthermore, the 
standard developers felt that it would not be acceptable to the community of POSIX developers, 
so it was later changed to be a format more closely related to historical practice on POSIX 
systems. 

The prefix and name split of path names in ustar was replaced by the single path extended 
header record for simplicity. 

The concept of a global extended header (typeflag g) was controversial. If this were applied to an 
archive being recorded on magnetic tape, a few unreadable blocks at the beginning of the tape 
could be a serious problem; a utility attempting to extract as many files as possible from a 
damaged archive could lose a large percentage of file header information in this case. However, 
if the archive were on a reliable medium, such as a CD-ROM, the global extended header offers 
considerable potential size reductions by eliminating redundant information. Thus, the text 
warns against using the global method for unreliable media and provides a method for 
implanting global information in the extended header for each file, rather than in the typeflag g 
records. 
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No facility for data translation or filtering on a per-file basis is included because the standard 
developers could not invent an interface that would allow this in an efficient manner. If a filter, 
such as encryption or compression, is to be applied to all the files, it is more efficient to apply the 
filter to the entire archive as a single file. The standard developers considered interfaces that 
would invoke a shell script for each file going into or out of the archive, but the system overhead 
in this approach was considered to be too high. 

One such approach would be to have filter= records that give a path name for an executable. 
When the program is invoked, the file and archive would be open for standard input/output 
and all the header fields would be available as environment variables or command-line 
arguments. The standard developers did discuss such schemes, but they were omitted from 
IEEE Std. 1003.1-200x due to concerns about excessive overhead. Also, the program itself would 
need to be in the archive if it were to be used portably. 

There is currently no portable means of identifying the character set(s) used for a file in the file 
system. Therefore, pax has not been given a mechanism to generate charset records 
automatically. The only portable means of doing this is for the user to write the archive using the 
-ocharset =string command line option. This assumes that all of the files in the archive use the 
same encoding. The "implementation-dependent” text is included to allow for a system that can 
identify the encodings used for each of its files. 

The table of standards that accompanies the charset record description is acknowledged to be 
very limited. Only a limited number of character set standards is reasonable for maximal 
interchange. Any character set is, of course, possible by prior agreement. It was suggested that 
EBCDIC be listed, but it was omitted because it is not defined by a formal standard. Formal 
standards, and then only those with reasonably large followings, can be included here, simply as 
a matter of practicality. The <value> s represent names of officially registered charactersets in the 
format required by the ISO 2375:1985 standard. 

The normal comma or <blank>-separated list rules are not followed in the case of keyword 
options to allow ease of argument parsing for getopts. 

Further information on character encodings is in pax Archive Character Set Encoding/Decoding 
on page 768. 

The standard developers have reserved keyword name space for vendor extensions. It is 
suggested that the format to be used is: 

VENDOR.keyword 

where VENDOR is the name of the vendor or organization in all uppercase letters. It is further 
suggested that the key wo rd following the period be named differently than any of the standard 
keywords so that it could be used for future standardization, if appropriate, by omitting the 
VENDOR prefix. 

The <length> field in the extended header record was included to make it simpler to step 
through the records, even if a record contains an unknown format (to a particular pax) with 
complex interactions of special characters. It also provides a minor integrity checkpoint within 
the records to aid a program attempting to recover files from a damaged archive. 

There are no extended header versions of the devmajor and devminor fields because the 
unspecified format ustar header field should be sufficient. If they are not, vendor-specific 
extended keywords (such as VENDOR.devmajor) should be used. 

Device and /'-number labeling of files was not adopted from cpio ; files are interchanged strictly 
on a symbolic name basis, as in ustar. 
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Just as with the ustar format descriptions, the new format makes no special arrangements for 
multi-volume archives. Each of the pax archive types is assumed to be inside a single POSIX file 
and splitting that file over multiple volumes (diskettes, tape cartridges, and so on), processing 
their labels, and mounting each in the proper sequence are considered to be implementation 
details that cannot be described portably. 

The pax format is intended for interchange, not only for backup on a single (family of) systems. It 
is not as densely packed as might be possible for backup: 

• It contains information as coded characters that could be coded in binary. 

• It identifies extended records with name fields that could be omitted in favor of a fixed-field 
layout. 

• It translates names into a portable character set and identifies locale-related information, 
both of which are probably unnecessary for backup. 

The requirements on restoring from an archive are slightly different from the historical wording, 
allowing for non-monolithic privilege to bring forward as much as possible. In particular, 
attributes such as "high performance file" might be broadly but not universally granted while 
set-user-ID or choivn() might be much more restricted. There is no implication in 
IEEE Std. 1003.1-200x that the security information be honored after it is restored to the file 
hierarchy, in spite of what might be improperly inferred by the silence on that topic. That is a 
topic for another standard. 

Links are recorded in the fashion described here because a link can be to any file type. It is 
desirable in general to be able to restore part of an archive selectively and restore all of those 
files completely. If the data is not associated with each link, it is not possible to do this. 
However, the data associated with a file can be large, and when selective restoration is not 
needed, this can be a significant burden. The archive is structured so that files that have no 
associated data can always be restored by the name of any link name of any link, and the user 
may choose whether data is recorded with each instance of a file that contains data. The format 
permits mixing of both types of links in a single archive; this can be done for special needs, and 
pax is expected to interpret such archives on input properly, despite the fact that there is no pax 
option that would force this mixed case on output. (When -o linkdata is used, the output must 
contain the duplicate data, but the implementation is free to include it or omit it when -o 
linkdata is not used.) 

The time values are included as extended header records for those implementations needing 
more than the eleven octal digits allowed by the ustar format. Even though some 
implementations can support finer file-time granularities than seconds, the normative text 
requires support only for seconds since the Epoch because the ISO POSIX-1 standard states them 
that way. The ustar format includes only mtime ; the new format adds atime and dime for 
symmetry. The atime access time restored to the file system will be affected by the -p a and -p e 
options. The dime creation time (actually inode modification time) is described with 
"appropriate privilege" so that it can be ignored when writing to the file system. POSIX does not 
provide a portable means to change file creation time. Nothing is intended to prevent a non¬ 
portable implementation of pax from restoring the value. 

The gid, size, and nid extended header records were included to allow expansion beyond the 
sizes specified in the regular tar header. New file system architectures are emerging that will 
exhaust the 12-digit size field. There are probably not many systems requiring more than 8 digits 
for user and group IDs, but the extended header values were included for completeness, 
allowing overrides for all of the decimal values in the tar header. 

The standard developers intended to describe the effective results of pax with regard to file 
ownerships and permissions; implementations are not restricted in timing or sequencing the 
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restoration of such, provided the results are as specified. 

Much of the text describing the extended headers refers to use in "write or copy modes". The 
copy mode references are due to the normative text: "The effect of the copy shall be as if the 
copied files were written to an archive file and then subsequently extracted ...". There is 
certainly no way to test whether pax is actually generating the extended headers in copy mode, 
but the effects must be as if it had. 

pax Archive Character Set Encoding/Decoding 

There is a need to exchange archives of files between systems of different native codesets. File 
names, group names, and user names must be preserved to the fullest extent possible when an 
archive is read on the receiving platform. Translation of the contents of files is not within the 
scope of the pax utility. 

There will also be the need to represent glyphs that are not available on the receiving platform. 
(A glyph is commonly called a character, but without any reference to a specific encoding of that 
character. The term glyph refers to the symbol itself.) These unsupported glyphs cannot be 
automatically folded to the local set of glyphs due to the chance of collisions. This could result in 
overwriting previous extracted files from the archive or pre-existing files on the system. 

For these reasons, the codeset used to represent glyphs within the extended header records of 
the pax archive must be sufficiently rich to handle all commonly used character sets. The fields 
requiring translation include, at a minimum, file names, user names, group names, and link path 
names. Implementations may wish to have localized extended key wo rd s that use non-portable 
characters. 

The standard developers considered the following options: 

• The archive creator specifies the well-defined name of the source codeset. The receiver must 
then recognize the codeset name and perform the appropriate translations to the destination 
codeset. 

• The archive creator includes within the archive the character mapping table for the source 
codeset used to encode extended header records. The receiver must then read the character 
mapping table and perform the appropriate translations to the destination codeset. 

• The archive creator translates the extended header records in the source codeset into a 
canonical form. The receiver must then perform the appropriate translations to the 
destination codeset. 

The approach that incorporates the name of the source codeset poses the problem of codeset 
name registration, and makes the archive useless to pax archive decoders that do not recognize 
that codeset. 

Because parts of an archive may be corrupted, the standard developers felt that including the 
character map of the source codeset was too fragile. The loss of this one key component could 
result in making the entire archive useless. (The difference between this and the global extended 
header decision was that the latter has a workaround—duplicating extended header records on 
unreliable media—but this would be too burdensome for large character set maps.) 

Both of the above approaches also put an undue burden on the pax archive receiver to handle the 
cross-product of all source and destination codesets. 

To simplify the translation from the source codeset to the canonical form and from the canonical 
form to the destination codeset, the standard developers decided that the internal representation 
should be a stateless encoding. A stateless encoding is one where each codepoint has the same 
meaning, without regard to the decoder being in a specific state. An example of a stateful 
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29467 encoding would be the Japanese Shift-JIS; an example of a stateless encoding would be the 

29468 ISO/IEC 646:1991 standard (equivalent to 7-bit ASCII). 

29469 For these reasons, the standard developers decided to adopt a canonical format for the 

29470 representation of file information strings. The obvious, well-endorsed candidate is the 

29471 ISO/IEC 10646-1:1993 standard (based in part on Unicode), which can be used to represent the 

29472 glyphs of virtually all standardized character sets. The standard developers initially agreed upon 

29473 using UCS2 (16-bit Unicode) as the internal representation. This repertoire of glyphs provides a 

29474 sufficiently rich set to represent all commonly-used codesets. 

29475 However, the standard developers found that the 16-bit Unicode representation had some 

29476 problems. It forced the issue of standardizing byte ordering. The 2-byte length of each character 

29477 made the extended header records twice as long for the case of strings coded entirely from 

29478 historical 7-bit ASCII. For these reasons, the standard developers chose the UTF-8 defined in the 

29479 ISO/IEC 10646-1:1993 standard. This multi-byte representation encodes UCS2 or UCS4 

29480 characters reliably and deterministically, eliminating the need for a canonical byte ordering. In 

29481 addition, NUL octets and other characters possibly confusing to POSIX file systems do not 

29482 appear, except to represent themselves. It was realized that certain national codesets take up 

29483 more space after the encoding, due to their placement within the UCS range; it was felt that the 

29484 usefulness of the encoding of the names outweighs the disadvantage of size increase for file, 

29485 user, and group names. 

29486 The encoding of UTF-8 is as follows: 


29487 

UCS4 Hex Encoding 

UTF-8 Binary Encoding 



29488 

00000000-0000007F 

Oxxxxxxx 





29489 

00000080-000007FF 

llOxxxxx 

1Oxxxxxx 




29490 

00000800-0000FFFF 

11lOxxxx 

1Oxxxxxx 

lOxxxxxx 



29491 

00010000-001FFFFF 

llllOxxx 

lOxxxxxx 

lOxxxxxx 

lOxxxxxx 


29492 

00200000-03FFFFFF 

lllllOxx 

1Oxxxxxx 

lOxxxxxx 

lOxxxxxx 

lOxxxxxx 

29493 

04000000-7FFFFFFF 

llllllOx 

lOxxxxxx 

lOxxxxxx 

lOxxxxxx 

lOxxxxxx lOxxxxxx 


29494 where each ' x' represents a bit value from the character being translated. 


29495 ustar Interchange Format 

29496 The description of the ustar format reflects numerous enhancements over pre-1988 versions of 

29497 the historical tar utility. The goal of these changes was not only to provide the functional 

29498 enhancements desired, but also to retain compatibility between new and old versions. This 

29499 compatibility has been retained. Archives written using the old archive format are compatible 

29500 with the new format. 

29501 Implementors should be aware that the previous file format did not include a mechanism to 

29502 archive directory type files. For this reason, the convention of using a file name ending with 

29503 slash was adopted to specify a directory on the archive. 

29504 The total size of the name and prefix fields have been set to meet the minimum requirements for 

29505 {PATH_MAX}. If a path name will fit within the name field, it is recommended that the path 

29506 name be stored there without the use of the prefix field. Although the name field is known to be 

29507 too small to contain {PATH_MAX} characters, the value was not changed in this version of the 

29508 archive file format to retain backward compatibility, and instead the prefix was introduced. 

29509 Also, because of the earlier version of the format, there is no way to remove the restriction on the 

29510 linkname field being limited in size to just that of the name field. 

29511 The size field is required to be meaningful in all implementation extensions, although it could be 

29512 zero. This is required so that the data blocks can always be properly counted. 
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It is suggested that if device special files need to be represented that cannot be represented in the 
standard format that one of the extension types (A-Z) be used, and that the additional 
information for the special file be represented as data and be reflected in the size field. 

Attempting to restore a special file type, where it is converted to ordinary data and conflicts 
with an existing file name, need not be specially detected by the utility. If run as an ordinary 
user, pax should not be able to overwrite the entries in, for example, /dev in any case (whether 
the file is converted to another type or not). If run as a privileged user, it should be able to do so, 
and it would be considered a bug if it did not. The same is true of ordinary data files and 
similarly named special files; it is impossible to anticipate the needs of the user (who could 
really intend to overwrite the file), so the behavior should be predictable (and thus regular) and 
rely on the protection system as required. 

The value 7 in the typeflag field is intended to define how contiguous files can be stored in a 
ustar archive. IEEE Std. 1003.1-200x does not require the contiguous file extension, but does 
define a standard way of archiving such files so that all conforming systems can interpret these 
file types in a meaningful and consistent manner. On a system that does not support extended 
file types, the pax utility should do the best it can with the file and go on to the next. 

The file protection modes are those conventionally used by the Is utility. This is extended 
beyond the usage in the ISO POSIX-2 standard to support the "shared text" or "sticky" bit. It is 
intended that the conformance document should not document anything beyond the existence 
of and support of such a mode. Further extensions are expected to these bits, particularly with 
overloading the set-user-ID and set-group-ID flags. 

cpio Interchange Format 

The reference to appropriate privilege in the cpio format refers to an error on standard output; 
the ustar format does not make comparable statements. 

The model for this format was the historical System V cpio-c data interchange format. This 
model documents the portable version of the cpio format and not the binary version. It has the 
flexibility to transfer data of any type described within IEEE Std. 1003.1-200x, yet is extensible to 
transfer data types specific to extensions beyond IEEE Std. 1003.1-200x (for example, contiguous 
files). Because it describes existing practice, there is no question of maintaining upward 
compatibility. 

cpio Header 

There has been some concern that the size of the c_ino field of the header is too small to handle 
those systems that have very large inode numbers. However, the c_ino field in the header is used 
strictly as a hard-link resolution mechanism for archives. It is not necessarily the same value as 
the inode number of the file in the location from which that file is extracted. 

The name c_magic is based on historical usage. 

cpio File Name 

For most historical implementations of the cpio utility, |PATH_MAX} octets can be used to 
describe the path name without the addition of any other header fields (the NUL character 
would be included in this count). |PATH_MAX} is the minimum value for path name size, 
documented as 256 bytes. However, an implementation may use c_namesize to determine the 
exact length of the path name. With the current description of the <cpio.h> header, this path 
name size can be as large as a number that is described in six octal digits. 

Two values are documented under the c_mode field values to provide for extensibility for known 
file types: 
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29558 Notes to Reviewers 

29559 This section with side shading will not appear in the final copy. - Ed. 

29560 Note that the sockets extension below needs to be integrated, now that sockets have been 

29561 merged 

29562 0110 000 Reserved for contiguous files. The implementation may treat the rest of the 

29563 information for this archive like a regular file. If this file type is undefined, the 

29564 implementation may create the file as a regular file. 

29565 0140 0 00 Reserved for sockets. If this type is undefined on the target system, the 

29566 implementation may decide to ignore this file type and output a warning message. 

29567 This provides for extensibility of the cpio format while allowing for the ability to read old 

29568 archives. Files of an unknown type may be read as "regular files" on some implementations. On 

29569 a system that does not support extended file types, the pax utility should do the best it can with 

29570 the file and go on to the next. 

29571 FUTURE DIRECTIONS 

29572 None. 

29573 SEE ALSO 

29574 cp, ed, getopts, printf, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <cpio.h>, 

29575 the System Interfaces volume of IEEE Std. 1003.1-200x, chown (), creat( ), mkdir( ), stat( ), write{) 

29576 CHANGE HISTORY 

29577 First released in Issue 4. 

29578 Issue 5 

29579 A note is added to the APPLICATION USAGE indicating that the cpio and tar formats can only 

29580 support files up to 8 gigabytes in size. 

29581 Issue 6 

29582 The pax utility is aligned with the IEEE P1003.2b draft standard: 

29583 • Support has been added for symbolic links in the options and interchange formats. 

29584 • A new format has been devised, based on extensions to ustar. 

29585 • References to the "extended" tar and cpio formats derived from the POSIX.1-1990 standard 

29586 have been changed to remove the "extended" adjective because this could cause confusion 

29587 with the extended tar header added in this revision. (All references to tar are actually to 

29588 ustar). 
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NAME 

pr — print files 

SYNOPSIS 

pr [ +page][-column ][— adFmrt] [— e[char][gap ]][— h header] [-i[char] [gap]] 

xsi [—1 lines] [— n[char] [width]] [— o offset] [— s [char] ] [— w width] [— fp] 

[file ...] 

DESCRIPTION 

The pr utility is a printing and pagination filter. If multiple input files are specified, each shall be 
read, formatted, and written to standard output. By default, the input shall be separated into 66- 
line pages, each with: 

• A 5-line header that includes the page number, date, time, and the path name of the file 

• A 5-line trailer consisting of blank lines 

If standard output is associated with a terminal, diagnostic messages shall be deferred until the 
pr utility has completed processing. 

When options specifying multi-column output are specified, output text columns shall be of 
equal width; input lines that do not fit into a text column shall be truncated. By default, text 
columns shall be separated with at least one <blank> character. 

OPTIONS 

The pr utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Section 12.2, Utility Syntax Guidelines, except that: the page option has a ' +' delimiter; page and I 
column can be multi-digit numbers; some of the option-arguments are optional; and some of the 
option-arguments cannot be specified as separate arguments from the preceding option letter. In 
particular, the -s option does not allow the option letter to be separated from its argument, and 
the options -e, -i, and -n require that both arguments, if present, not be separated from the 
option letter. 

The following options shall be supported. In the following option descriptions, column, lines, 
offset, page, and width are positive decimal integers; yap is a non-negative decimal integer. 

+page Begin output at page number page of the formatted input. 

-column Produce multi-column output that is arranged in column columns (the default shall 
be 1) and is written down each column in the order in which the text is received 
from the input file. This option should not be used with -m. The options -e and -i 
shall be assumed for multiple text-column output. Whether or not text columns 
are produced with identical vertical lengths is unspecified, but a text column shall 
never exceed the length of the page (see the -1 option). When used with -t, use the 
minimum number of lines to write the output. 

-a Modify the effect of the -column option so that the columns are filled across the 

page in a round-robin order (for example, when column is 2, the first input line 
heads column 1, the second heads column 2, the third is the second line in column 
1, and so on). 

-d Produce output that is double-spaced; append an extra <newline> character 

following every <newline> character found in the input. 

-e[char][gap] 

Expand each input <tab> character to the next greater column position specified 
by the formula n*gap+1, where n is an integer > 0. If gap is zero or is omitted, it 
shall default to 8. All <tab> characters in the input shall be expanded into the 
appropriate number of <space> characters. If any non-digit character, char, is 
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29635 


specified, it shall be used as the input <tab> character. 

29636 XSI 

29637 

29638 

-f 

Use a <form-feed> character for new pages, instead of the default behavior that 
uses a sequence of <newline> characters. Pause before beginning the first page if 
the standard output is associated with a terminal. 

29639 

29640 

-F 

Use a <form-feed> character for new pages, instead of the default behavior that 
uses a sequence of <newline> characters. 

29641 

-h header 

Use the string header to replace the contents of the file operand in the page header. 

29642 

29643 

29644 

29645 

29646 

29647 

-i [char][gap] 

In output, replace multiple <space> characters with <tab> characters wherever 
two or more adjacent <space> characters reach column positions gap+1, 2* gap +1, 
3* gap+1, and so on. I f gap is zero or is omitted, default tab settings at every eighth 
column position shall be assumed. If any non-digit character, char, is specified, it 
shall be used as the output <tab> character. 

29648 

29649 

29650 

-1 lines 

Override the 66-line default and reset the page length to lines. If lines is not greater 
than the sum of both the header and trailer depths (in lines), the pr utility shall 
suppress both the header and trailer, as if the -t option were in effect. 

29651 

29652 

29653 

29654 

-m 

Merge files. Standard output shall be formatted so the pr utility writes one line 
from each file specified by a file operand, side by side into text columns of equal 
fixed widths, in terms of the number of column positions. Implementations shall 
support merging of at least nine file operands. 

29655 

29656 

29657 

29658 

29659 

29660 

-n [char][width] 

Provide width -digit line numbering (default for width shall be 5). The number shall 
occupy the first ividth column positions of each text column of default output or 
each line of -m output. If char (any non-digit character) is given, it shall be 
appended to the line number to separate it from whatever follows (default for char 
is a <tab> character). 

29661 

29662 

29663 

-o offset 

Each line of output shall be preceded by offset <space>s. If the -o option is not 
specified, the default offset shall be zero. The space taken is in addition to the 
output line width (see the -w option below). 

29664 

29665 

29666 

-P 

Pause before beginning each page if the standard output is directed to a terminal 
(pr shall write an <alert> character to standard error and wait for a <carriage- 
return> character to be read on /dev/tty). 

29667 

-r 

Write no diagnostic reports on failure to open files. 

29668 

29669 

-s [char] 

Separate text columns by the single character char instead of by the appropriate 
number of <space> characters (default for char shall be the <tab> character). 

29670 

29671 

29672 

-t 

Write neither the five-line identifying header nor the five-line trailer usually 
supplied for each page. Quit writing after the last line of each file without spacing 
to the end of the page. 

29673 

29674 

29675 

29676 

-w ividth 

Set the width of the line to width column positions for multiple text-column output 
only. If the -w option is not specified and the -s option is not specified, the default 
width shall be 72. If the -w option is not specified and the -s option is specified, 
the default width shall be 512. 

29677 


For single column output, input lines shall not be truncated. 
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29678 OPERANDS 

29679 The following operand shall be supported: 

29680 file A path name of a file to be written. If no file operands are specified, or if a file 

29681 operand is ' - ', the standard input shall be used. 

29682 STDIN 

29683 The standard input shall be used only if no file operands are specified, or if a file operand is ' . 

29684 See the INPUT FILES section. 


29685 INPUT FILES 

29686 The input files shall be text files. 

29687 The file /dev/tty is used to read responses required by the -p option. 

29688 ENVIRONMENT VARIABLES 


29689 

The following environment variables shall affect the execution of pr: 

29690 

29691 

29692 

29693 

29694 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

29695 

29696 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

29697 

29698 

29699 

29700 

29701 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and which characters are defined as printable (character 
class print). Non-printable characters are still written to standard output, but are 
not counted for the purpose for column-width and line-length calculations. 

29702 

29703 

29704 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

29705 

LCJTIME 

Determine the format of the date and time for use in writing header lines. 

29706 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

29707 

TZ 

Determine the timezone for use in writing header lines. 


29708 ASYNCHRONOUS EVENTS 

29709 If pr receives an interrupt while writing to a terminal, it shall flush all accumulated error 

29710 messages to the screen before terminating. 


29711 STDOUT 

29712 The pr utility output shall be a paginated version of the original file (or files). This pagination 

29713 shall be accomplished using either <form-feed> characters or a sequence of <newline> 

29714 xsi characters, as controlled by the -F or -f option. Page headers shall be generated unless the -t 

29715 option is specified. The page headers shall be of the form: 

29716 "\n\n%s %s Page %d\n\n\n", <output of date>, <file>, <page number> 


29717 In the POSIX locale, the <ontput ofdnte> field, representing the date and time of last modification 

29718 of the input file (or the current date and time if the input file is standard input), shall be 

29719 equivalent to the output of the following command as it would appear if executed at the given 

29720 time: 
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29721 date "+%b %e %H:%M %Y" 

29722 without the trailing <newline> character, if the page being written is from standard input. If the 

29723 P a g e being written is not from standard input, in the POSIX locale, the same format shall be 

29724 used, but the time used shall be the modification time of the file corresponding to file instead of 

29725 the current time. When the LC_TIME locale category is not set to the POSIX locale, a different 

29726 format and order of presentation of this field may be used. 

29727 If the standard input is used instead of a file operand, the <file> field shall be replaced by a null 

29728 string. 

29729 If the -h option is specified, the < :file> field shall be replaced by the header argument. 

29730 STDERR 

29731 man Used for diagnostic messages and for alerting the terminal when -p is specified. 

29732 OUTPUT FILES 

29733 None. 

29734 EXTENDED DESCRIPTION 

29735 None. 

29736 EXIT STATUS 

29737 The following exit values shall be returned: 

29738 0 Successful completion. I 

29739 >0 An error occurred. 

29740 CONSEQUENCES OF ERRORS 

29741 Default. 

29742 APPLICATION USAGE 

29743 None. 

29744 EXAMPLES 

29745 1. Print a numbered list of all files in the current directory: 

29746 Is —a | pr —n —h "Files in $ (pwd) . " 

29747 2. Print filel and file2 as a double-spaced, three-column listing headed by "file list": 

29748 pr —3d — h "file list" filel file2 

29749 3. Write filel on file2, expanding tabs to columns 10,19,28,...: 

29750 pr —e9 —t <filel >file2 

29751 RATIONALE 

29752 This utility is one of those that does not follow the Utility Syntax Guidelines because of its 

29753 historical origins. The standard developers could have added new options that obeyed the 

29754 guidelines (and marked the old options obsolescent) or devised an entirely new utility; there are 

29755 examples of both actions in this volume of IEEE Std. 1003.1-200x. Because of its widespread use 

29756 by historical applications, the standard developers decided to exempt this version of pr from 

29757 many of the guidelines. 

29758 Implementations are required to accept option-arguments to the -h, -1, -o, and -w options I 

29759 whether presented as part of the same argument or as a separate argument to pr, as suggested by 

29760 the Utility Syntax Guidelines. The -n and -s options, however, are specified as in historical 

29761 practice because they are frequently specified without their optional arguments. If a <blank> 

29762 were allowed before the option-argument in these cases, a file operand could mistakenly be 
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interpreted as an option-argument in historical applications. 

The text about the minimum number of lines in multi-column output was included to ensure 
that a best effort is made in balancing the length of the columns. There are known historical 
implementations in which, for example, 60-line files are listed by pr -1 as one column of 56 lines 
and a second of 4. Although this is not a problem when a full page with headers and trailers is 
produced, it would be relatively useless when used with -t. 

Historical implementations of the pr utility have differed in the action taken for the -f option. 
BSD uses it as described here for the -F option; System V uses it to change trailing <newline>s 
on each page to a <form-feed> and, if standard output is a TTY device, sends an <alert> to 
standard error and reads a line from /dev/tty before the first page. There were strong arguments 
from both sides of this issue concerning historical practice and additional arguments against the 
System V -f behavior, on the grounds that having the behavior of an option change depending 
on where output is directed was not a modular design. Therefore, the -f option is not specified 
and the -F option has been added. 

The <output ofdate> field in the -1 format is specified only for the POSIX locale. As noted, the I 
format can be different in other locales. No mechanism for defining this is present in this volume I 
of IEEE Std. 1003.1-200x, as the appropriate vehicle is a messaging system; that is, the format 
should be specified as a “message". 

FUTURE DIRECTIONS 

It is possible that a new interface that conforms to the Utility Syntax Guidelines will be 
introduced. 

SEE ALSO 

expand, Ip 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The -p option is added. 

The normative text is reworded to avoid use of the term "must" for application requirements. 
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29795 NAME 

29796 printf — write formatted output 

29797 SYNOPSIS 

29798 printf format [argument... ] 

29799 DESCRIPTION 

29800 The printf utility shall write formatted operands to the standard output. The argument operands 

29801 shall be formatted under control of the format operand. 

29802 OPTIONS 

29803 None. 


29804 OPERANDS 

29805 The following operands shall be supported: 


29806 format 

29807 


A string describing the format to use to write the remaining operands. See the 
EXTENDED DESCRIPTION section. 


29808 

29809 


argument The strings to be written to standard output, under the control of format. See the 
EXTENDED DESCRIPTION section. 


29810 STDIN 

29811 Not used. 


29812 INPUT FILES 

29813 None. 


29814 ENVIRONMENT VARIABLES 

29815 The following environment variables shall affect the execution of printf: 


29816 

29817 

29818 

29819 

29820 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


29821 LC_ALL If set to a non-empty string value, override the values of all the other 

29822 internationalization variables. 


29823 

29824 

29825 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


29826 LC_MESSAGES 

29827 Determine the locale that should be used to affect the format and contents of 

29828 diagnostic messages written to standard error. 


29829 LC_NUMERIC 

29830 Determine the locale for numeric formatting. It shall affect the format of numbers 

29831 written using the e, E,f, g, and G conversion characters (if supported). 

29832 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


29833 ASYNCHRONOUS EVENTS 

29834 Default. 
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29835 STDOUT 

29836 See the EXTENDED DESCRIPTION section. 

29837 STDERR 

29838 Used only for diagnostic messages. 

29839 OUTPUT FILES 

29840 None. 

29841 EXTENDED DESCRIPTION 

29842 The format operand shall be used as the format string described in the System Interface I 

29843 Definitions volume of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation with the following I 

29844 exceptions: I 

29845 1. A <space> character in the format string, in any context other than a flag of a conversion I 

29846 specification, shall be treated as an ordinary character that is copied to the output. 

29847 2. A ' A' character in the format string shall be treated as a 'A' character, not as a <space> 

29848 character. 


3. In addition to the escape sequences shown in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 5, File Format Notation ('W, ' \a', '\b', ' \ f', ' \n', 
' \r ' , ' \t' , ' \v' ), " \ddd", where ddd is a one, two, or three-digit octal number, shall be 
written as a byte with the numeric value specified by the octal number. 

4. The implementation shall not precede or follow output from the d or u conversion 
specifications with <blank> characters not specified by the format operand. 

5. The implementation shall not precede output from the o conversion specification with 
zeros not specified by the format operand. 

6. The e, E,f, g, and G conversion specifications need not be supported. 

7. An additional conversion character, b, shall be supported as follows. The argument shall 
be taken to be a string that may contain backslash-escape sequences. The following 
backslash-escape sequences shall be supported: 

— The escape sequences listed in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 5, File Format Notation ('\\', ' \a', ' \b', '\f', 
'\n','\r','\t','\v'), which shall be converted to the characters they represent 

— "\0ddd", where ddd is a zero, one, two, or three-digit octal number that shall be 
converted to a byte with the numeric value specified by the octal number 

— ' \c', which shall not be written and shall cause printf to ignore any remaining 
characters in the string operand containing it, any remaining string operands, and any 
additional characters in the format operand 

The interpretation of a backslash followed by any other sequence of characters is 
unspecified. 

Bytes from the converted string shall be written until the end of the string or the number of 
bytes indicated by the precision specification is reached. If the precision is omitted, it shall 
be taken to be infinite, so all bytes up to the end of the converted string shall be written. 

8. For each specification that consumes an argument, the next argument operand shall be 
evaluated and converted to the appropriate type for the conversion as specified below. 

9. The format operand shall be reused as often as necessary to satisfy the argument operands. 
Any extra c or s conversion specifications shall be evaluated as if a null string argument 
were supplied; other extra conversion specifications shall be evaluated as if a zero 
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29879 argument were supplied. If the format operand contains no conversion specifications and 

29880 argument operands are present, the results are unspecified. 

29881 10. If a character sequence in the format operand begins with a ' %' character, but does not 

29882 form a valid conversion specification, the behavior is unspecified. 

29883 The argument operands shall be treated as strings if the corresponding conversion character is b, 

29884 c, or s; otherwise, it shall be evaluated as a C constant, as described by the ISO C standard, with 

29885 the following extensions: 

29886 • A leading plus or minus sign shall be allowed. 

29887 • If the leading character is a single-quote or double-quote, the value shall be the numeric 

29888 value in the underlying codeset of the character following the single-quote or double-quote. 

29889 If an argument operand cannot be completely converted into an internal value appropriate to 

29890 the corresponding conversion specification, a diagnostic message shall be written to standard 

29891 error and the utility shall not exit with a zero exit status, but shall continue processing any 

29892 remaining operands and shall write the value accumulated at the time the error was detected to 

29893 standard output. 

29894 EXIT STATUS 

29895 The following exit values shall be returned: 

29896 0 Successful completion. 

29897 >0 An error occurred. 

29898 CONSEQUENCES OF ERRORS 

29899 Default. 

29900 APPLICATION USAGE 

29901 The floating-point formatting conversion specifications of printf () are not required because all 

29902 arithmetic in the shell is integer arithmetic. The azvk utility performs floating-point calculations 

29903 and provides its own printf function. The be utility can perform arbitrary-precision floating- 

29904 point arithmetic, but does not provide extensive formatting capabilities. (This printf utility 

29905 cannot really be used to format be output; it does not support arbitrary precision.) 

29906 Implementations are encouraged to support the floating-point conversions as an extension. 

29907 Note that this printf utility, like the printf ( ) function defined in the System Interfaces volume of 

29908 IEEE Std. 1003.1-200x on which it is based, makes no special provision for dealing with multi- 

29909 byte characters when using the %c conversion specification or when a precision is specified in a 

29910 %b or %s conversion specification. Applications should be extremely cautious using either of 

29911 these features when there are multi-byte characters in the character set. 

29912 No provision is made in this volume of IEEE Std. 1003.1-200x which allows field widths and 

29913 precisions to be specified as ' *' since the ' *' can be replaced directly in the format operand 

29914 using shell variable substitution. Implementations can also provide this feature as an extension 

29915 if they so choose. 

29916 Hexadecimal character constants as defined in the ISO C standard are not recognized in the 

29917 format operand because there is no consistent way to detect the end of the constant. Octal 

29918 character constants are limited to, at most, three octal digits, but hexadecimal character 

29919 constants are only terminated by a non-hex-digit character. In the ISOC standard, the "##" 

29920 concatenation operator can be used to terminate a constant and follow it with a hexadecimal 

29921 character to be written. In the shell, concatenation occurs before the printf utility has a chance to 

29922 parse the end of the hexadecimal constant. 
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29923 The %b conversion specification is not part of the ISO C standard; it has been added here as a 

29924 portable way to process backslash escapes expanded in string operands as provided by the echo 

29925 utility. See also the APPLICATION USAGE section of echo on page 366 for ways to use printf as a 

29926 replacement for all of the traditional versions of the echo utility. 

29927 If an argument cannot be parsed correctly for the corresponding conversion specification, the 

29928 printf utility is required to report an error. Thus, overflow and extraneous characters at the end 

29929 of an argument being used for a numeric conversion shall be reported as errors. 

29930 Notes to Reviewers 

29931 This section with side shading will not appear in the final copy. - Ed. 

29932 Is the following text normative? If so, where should it be moved to? 

29933 It is not considered an error if an argument operand is not completely used for a c or s 

29934 conversion or if a string operand's first or second character is used to get the numeric value of a 

29935 character. 

29936 EXAMPLES 

29937 To alert the user and then print and read a series of prompts: 

29938 printf "\aPlease fill in the following: \nName: " 

29939 read name 

29940 printf "Phone number: " 

29941 read phone 

29942 To read out a list of right and wrong answers from a file, calculate the percentage correctly, and 

29943 print them out. The numbers are right-justified and separated by a single <tab> character. The 

29944 percentage is written to one decimal place of accuracy: 

29945 while read right wrong ; do 

29946 percent = $(echo "scale=l; ($right*100)/($right + $wrong)" | be) 

29947 printf "%2d right\t%2d wrong\t (%s%%) \n" \ 

29948 $right $wrong $percent 

29949 done < database_file 

29950 The command: 

29951 printf "%5d%4d\n" 1 21 321 4321 54321 

29952 produces: 

29953 1 21 

29954 3 2 1 4 3 21 

29955 54321 0 

29956 Note that the format operand is used three times to print all of the given strings and that a ' 0' 

29957 was supplied by printf to satisfy the last %4 d conversion specification. 

29958 The printf utility is required to notify the user when conversion errors are detected while 

29959 producing numeric output; thus, the following results would be expected on an implementation 

29960 with 32-bit twos-complement integers when %d is specified as the format operand: 
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29961 




29962 

29963 

Argument 

Standard 

Output 

Diagnostic Output 

29964 

5a 

5 

printf: "5a" not completely converted 

29965 

9999999999 

2147483647 

printf: "9999999999" arithmetic overflow 

29966 


-2147483648 

printf: "-9999999999" arithmetic overflow 

29967 

ABC 

0 

printf: "ABC" expected numeric value 


29968 The diagnostic message format is not specified, but these examples convey the type of 

29969 information that should be reported. Note that the value shown on standard output is what 

29970 would be expected as the return value from the strtol() function as defined in the System 

29971 Interfaces volume of IEEE Std. 1003.1-200x. A similar correspondence exists between %w and 

29972 strtoid () and %e, %/, and %g (if the implementation supports floating-point conversions) and 

29973 strtod{). 

29974 In a locale using the ISO/IEC 646:1991 standard as the underlying codeset, the command: 

29975 printf "%d\n" 3 +3 -3 V3 \"+3 "'-3" 

29976 produces: I 

29977 3 Numeric value of constant 3 I 

29978 3 Numeric value of constant 3 I 

29979 -3 Numeric value of constant -3 I 

29980 51 Numeric value of the character ' 3 ' in the ISO/IEC 646:1991 standard codeset I 

29981 43 Numeric value of the character ' +' in the ISO/IEC 646:1991 standard codeset I 

29982 45 Numeric value of the character ' in the ISO/IEC 646:1991 standard codeset I 

29983 Note that in a locale with multi-byte characters, the value of a character is intended to be the I 

29984 value of the equivalent of the wchar_t representation of the character as described in the System 

29985 Interfaces volume of IEEE Std. 1003.1-200x. 

29986 RATIONALE 

29987 The printf utility was added to provide functionality that has historically been provided by echo. 

29988 However, due to irreconcilable differences in the various versions of echo extant, the version has 

29989 few special features, leaving those to this new printf utility, which is based on one in the Ninth 

29990 Edition system. 

29991 The EXTENDED DESCRIPTION section almost exactly matches the printf () function in the 

29992 ISO C standard, although it is described in terms of the file format notation in the System I 

29993 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 5, File Format Notation. I 

29994 FUTURE DIRECTIONS 

29995 None. 

29996 SEE ALSO 

29997 azvk, be, echo, the System Interfaces volume of IEEE Std. 1003.1-200x, printf () 

29998 CHANGE HISTORY 

29999 First released in Issue 4. 
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30000 NAME 

30001 prs — print an SCCS file (DEVELOPMENT) 

30002 SYNOPSIS 

30003 xsi prs [-a] [—d dataspec ] [—r[SJD]] file. . . 

30004 xsi prs [ —e | —1] —c cutoff [—d dataspec] file... 

30005 xsi prs [ —e | —1] —r[SJD][—d dataspec] file.. . 

30006 

30007 DESCRIPTION 

30008 The prs utility shall write to standard output parts or all of an SCCS file in a user-supplied 

30009 format. 


30010 OPTIONS 

30011 The prs utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

30012 Section 12.2, Utility Syntax Guidelines, except that the -r option has an optional option- I 

30013 argument. This optional option-argument cannot be presented as a separate argument. The 

30014 following options shall be supported: 


30015 

30016 

30017 


-d dataspec Specify the output data specification. The dataspec is a string consisting of SCCS 
file data keyivords (see Data Keywords on page 783) interspersed with optional 
user-supplied text. 


30018 

30019 

30020 


-r[S/D] Specify the SCCS identification string (SID) of a delta for which information is 
desired. If no SID option-argument is specified, the SID of the most recently 
created delta is assumed. 


30021 

30022 

30023 

30024 

30025 

30026 


-e 


-c cutoff 


Request information for all deltas created earlier than and including the delta 
designated via the -r option or the date-time given by the -c option. 

Request information for all deltas created later than and including the delta 
designated via the -r option or the date-time given by the -c option. 

Indicate the cutoff date-time, in the form: 

YY[MM[DD[HH[MM[SS] ] ] ] ] 


30027 

30028 

30029 


For the YY component, values in the range [69-99] shall refer to years in the 
twentieth century (1969 to 1999 inclusive); values in the range [00-68] shall refer to 
years in the twenty-first century (2000 to 2068 inclusive). 


30030 

30031 

30032 

30033 


No changes (deltas) to the SCCS file that were created after the specified cutoff 
date-time shall be included in the output. Units omitted from the date-time default 
to their maximum possible values; for example, -c 7502 is equivalent to 
-c 750228235959. 


30034 -a 

30035 

30036 


Request writing of information for both removed, that is, delta type-R (see rmdel on 
page 865) and existing, that is, delta type-D, deltas. If the -a option is not specified, 
information for existing deltas only shall be provided. 


30037 OPERANDS 

30038 The following operand shall be supported: 


30039 

30040 

30041 

30042 


file A path name of an existing SCCS file or a directory. If file is a directory, prs behaves 

as though each file in the directory were specified as a named file, except that 
non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. 
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30043 If a single instance file is specified as , the standard input shall be read; each 

30044 line of the standard input shall be taken to be the name of an SCCS file to be 

30045 processed. Non-SCCS files and unreadable files are silently ignored. 

30046 STDIN 

30047 The standard input shall be a text file used only when th e file operand is specified as ' - '. Each I 

30048 line of the text file shall be interpreted as an SCCS path name. 

30049 INPUT FILES 

30050 Any SCCS files displayed are files of an unspecified format. 


30051 ENVIRONMENT VARIABLES 

30052 The following environment variables shall affect the execution of prs: 


30053 

30054 

30055 

30056 

30057 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


30058 LC_ALL If set to a non-empty string value, override the values of all the other 

30059 internationalization variables. 


30060 

30061 

30062 


LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


30063 

30064 

30065 


LCJAESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


30066 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


30067 ASYNCHRONOUS EVENTS 

30068 Default. 


30069 STDOUT 

30070 The standard output shall be a text file whose format is dependent on the data keywords 

30071 specified with the -d option. 


30072 Data Keywords 

30073 Data keywords specify which parts of an SCCS file shall be retrieved and output. All parts of an I 

30074 SCCS file have an associated data keyword. A data keyword may appear in a dataspec multiple 

30075 times. 

30076 The information written by prs consists of: 

30077 1. The user-supplied text 

30078 2. Appropriate values (extracted from the SCCS file) substituted for the recognized data 

30079 keywords in the order of appearance in the dataspec 

30080 The format of a data keyword value is either simple ('S'), in which keyword substitution is 

30081 direct, or multi-line (' M' ) . 

30082 User-supplied text is any text other than recognized data keywords. A <tab> character is 

30083 specified by ' \t' and <newline> by ' \n' . When the -r option is not specified, the default 

30084 dataspec is: 
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30085 :PN::\n\n 

30086 and the following dataspec is used for each selected delta: 


30087 : Dt: \t :DL: \nMRs : \n : MR: COMMENTS : \n : C : \n 

30088 


30089 



SCCS File Data Keywords 



30090 

Keyword 

Data Item 

File Section 

Value 

Format 

30091 


Dt: 

Delta information 

Delta Table 

See below* 

S 

30092 


DL: 

Delta line statistics 

M 

:Li:/:Ld:/:Lu: 

S 

30093 


Li: 

Lines inserted by Delta 

M 

nnnnn 

S 

30094 


Ld: 

Lines deleted by Delta 

M 

nnnnn 

S 

30095 


Lu: 

Lines unchanged by Delta 

M 

nnnnn 

S 

30096 


DT: 

Delta type 

M 

D or R 

S 

30097 


I: 

SCCS ID string (SID) 

M 

See below*’ 1 ' 

S 

30098 


R: 

Release number 

M 

nnnn 

S 

30099 


L: 

Level number 

M 

nnnn 

S 

30100 


B: 

Branch number 

M 

nnnn 

S 

30101 


S: 

Sequence number 

M 

nnnn 

S 

30102 


D: 

Date delta created 

M 

:Dy:/:Dm:/:Dd: 

S 

30103 


Dy: 

Year delta created 

M 

nn 

S 

30104 


Dm: 

Month delta created 

M 

nn 

S 

30105 


Dd: 

Day delta created 

M 

nn 

S 

30106 


T: 

Time delta created 

M 

:Th:::Tm:::Ts: 

S 

30107 


Th: 

Hour delta created 

M 

nn 

S 

30108 


Tm: 

Minutes delta created 

M 

nn 

S 

30109 


Ts: 

Seconds delta created 

M 

nn 

S 

30110 


P: 

Programmer who created Delta 

M 

logname 

S 

30111 


DS: 

Delta sequence number 

M 

nnnn 

s 

30112 


DP: 

Predecessor Delta sequence 

M 

nnnn 

S 

30113 

30114 

:DI: 

number 

Sequence number of deltas 

M 

:Dn:/:Dx:/:Dg: 

S 

30115 

30116 


Dn: 

included, excluded or ignored 
Deltas included (sequence #) 

M 

:DS: :DS:... 

S 

30117 


Dx: 

Deltas excluded (sequence #) 

M 

:DS: :DS:... 

S 

30118 


Dg: 

Deltas ignored (sequence #) 

M 

:DS: :DS:... 

S 

30119 


MR: 

MR numbers for delta 

M 

text 

M 

30120 


C: 

Comments for delta 

H 

text 

M 

30121 


UN: 

User names 

User Names 

text 

M 

30122 


FL: 

Flag list 

Flags 

text 

M 

30123 


Y: 

Module type flag 

M 

text 

s 

30124 


MF: 

MR validation flag 

M 

yes or no 

S 

30125 


MP: 

MR validation program name 

M 

text 

S 

30126 


KF: 

Keyword error, warning flag 

M 

yes or no 

S 

30127 


KV: 

Keyword validation string 

M 

text 

s 

30128 


BF: 

Branch flag 

M 

yes or no 

S 

30129 


J: 

Joint edit flag 

M 

yes or no 

S 

30130 


LK: 

Locked releases 

M 

:R:... 

S 

30131 


Q: 

User-defined keyword 

M 

text 

S 
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30132 

30133 SCCS File Data Keywords 


30134 

Keyword 

Data Item 

File Section 

Value 

Format 

30135 


M: 

Module name 

M 

text 

S 

30136 


FB: 

Floor boundary 

M 

:R: 

S 

30137 


CB: 

Ceiling boundary 

M 

:R: 

S 

30138 


Ds: 

Default SID 

M 

:I: 

S 

30139 


ND: 

Null delta flag 

H 

yes or no 

S 

30140 


FD: 

File descriptive text 

Comments 

text 

M 

30141 


BD: 

Body 

Body 

text 

M 

30142 


GB: 

Gotten body 

" 

text 

M 

30143 


W: 

A form of zvhat string 

N/A 

:Z::M:\t:I: 

S 

30144 


A: 

A form of what string 

N/A 

:Z::Y: :M: :I::Z: 

S 

30145 


Z: 

what string delimiter 

N/A 

@ (#) 

S 

30146 


F: 

SCCS file name 

N/A 

text 

S 

30147 


PN: 

SCCS file path name 

N/A 

text 

S 


30148 * :Dt:=:DT: :I: :D: :T: :P: :DS: :DP: 

30149 ** :R:.:L:.:B:.:S: if the delta is a branch delta (:BF:= =yes) 

30150 :R:.:L: if the delta is not a branch delta (:BF:= =no) 

30151 STDERR 

30152 Used only for diagnostic messages. 

30153 OUTPUT FILES 

30154 None. 

30155 EXTENDED DESCRIPTION 

30156 None. 

30157 EXIT STATUS 

30158 The following exit values shall be returned: 

30159 0 Successful completion. 

30160 >0 An error occurred. 

30161 CONSEQUENCES OF ERRORS 

30162 Default. 


30163 APPLICATION USAGE 

30164 

None. 

30165 EXAMPLES 


30166 

1 . 

The following example: 

30167 


prs —d "User Names for :F: are:\n:UN:" s.file 

30168 


may write to standard output: 

30169 


User Names for s.file are: 

30170 


xyz 

30171 


131 

30172 


abc 

30173 

2. 

The following example: 

30174 


prs —d "Delta for pgm :M:: :I: — :D: By :P:" — r s.file 
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30175 may write to standard output: 

30176 Delta for pgm main.c: 3.7 — 77/12/01 By cas 

30177 3. As a special case: 

30178 prs s.file 

30179 may write to standard output: 

30180 s.file: 

30181 <blank line> 

30182 D 1.1 77/12/01 00:00:00 cas 1 000000/00000/00000 

30183 MRs: 

30184 bl78—12345 

30185 bl79—54321 

30186 COMMENTS: 

30187 this is the comment line for s.file initial delta 

30188 <blank line> 

30189 for each delta table entry of the D type. The only option allowed to be used with this 

30190 special case is the -a option. 

30191 RATIONALE 

30192 None. 

30193 FUTURE DIRECTIONS 

30194 A version of prs that fully supports the System Interface Definitions volume of 

30195 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines may be introduced in a future 

30196 issue. 

30197 SEE ALSO 

30198 admin, delta, get, what 

30199 CHANGE HISTORY 

30200 First released in Issue 2. 

30201 Issue 4 

30202 Format reorganized. 

30203 Exceptions to Utility Syntax Guidelines conformance noted. 

30204 Internationalized environment variable support mandated. 

30205 Issue 5 

30206 The phrase "in which keyword substitution is followed by a <newline>" is deleted from the end 

30207 of the second paragraph of Data Keywords on page 783. 

30208 The interpretation of the YY component of the -c cutoff argument is noted. 
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30212 

30213 

30214 

30215 

30216 

30217 

30218 

30219 

30220 

30221 

30222 

30223 

30224 

30225 

30226 

30227 

30228 

30229 

30230 

30231 

30232 

30233 

30234 

30235 

30236 

30237 

30238 

30239 

30240 

30241 

30242 

30243 

30244 

30245 

30246 

30247 

30248 

30249 

30250 

30251 
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NAME 

ps — report process status 

SYNOPSIS 

UP xsi ps [—aA] [—defl] [—G grouplist ] [—o format ] . . . [—p proclist ] [—t termlist] 

[—U userlist ][—g grouplist ][—n namelist ][—u userlist ] 


DESCRIPTION 

The ps utility shall write information about processes, subject to having the appropriate 

privileges to obtain information about those processes. 

By default, ps selects all processes with the same effective user ID as the current user and the 

same controlling terminal as the invoker. 

OPTIONS 

The ps utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported: 

-a Write information for all processes associated with terminals. Implementations 

may omit session leaders from this list. 

-A Write information for all processes. 

xsi -d Write information for all processes, except session leaders. 

xsi -e Write information for all processes. (Equivalent to -A.) 

xsi -f Generate a full listing. (See the STDOUT section for the contents of a full listing.) 

xsi -g grouplist Write information for processes whose session leaders are given in grouplist . The 

application shall ensure that the grouplist is a single argument in the form of a 
<blank> or comma-separated list. 

-G grouplist Write information for processes whose real group ID numbers are given in 
grouplist . The application shall ensure that the grouplist is a single argument in the 
form of a <blank> or comma-separated list. 

xsi -1 Generate a long listing. (See the STDOUT section for the contents of a long listing.) 


xsi 


XSI 


-n namelist Specify the name of an alternative system namelist file in place of the default. The 
name of the default file and the format of a namelist file are unspecified. 

-o format Write information according to the format specification given in format. This is 

fully described in the STDOUT section. Multiple -o options can be specified; the 
format specification shall be interpreted as the <space> character-separated 
concatenation of all the format option-arguments. 

-p proclist Write information for processes whose process ID numbers are given in proclist. 

The application shall ensure that the proclist is a single argument in the form of a 
<blank> or comma-separated list. 

-t termlist Write information for processes associated with terminals given in termlist. The 

application shall ensure that the termlist is a single argument in the form of a 
<blank> or comma-separated list. Terminal identifiers shall be given in one of two 
forms: the device's file name (for example, tty04) or, if the device's file name starts 
with tty, just the identifier following the characters tty (for example, "04"). 
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30252 

30253 

30254 

30255 

30256 

30257 

30258 

30259 

30260 

30261 

30262 

30263 

30264 

30265 

30266 

30267 

30268 

30269 

30270 

30271 

30272 

30273 

30274 

30275 

30276 

30277 

30278 

30279 

30280 

30281 

30282 

30283 

30284 

30285 

30286 

30287 

30288 

30289 

30290 

30291 

30292 

30293 

30294 

30295 


ps 


xsi -u userlist Write information for processes whose user ID numbers or login names are given 
in userlist. The application shall ensure that the userlist is a single argument in the 
form of a <blank> or comma-separated list. In the listing, the numerical user ID is 
written unless the -f option is used, in which case the login name is written. 

-U userlist Write information for processes whose real user ID numbers or login names are 
given in userlist. The application shall ensure that the userlist is a single argument 
in the form of a <blank> or comma-separated list. 

With the exception of -o format, all of the options shown are used to select processes. If any are 
specified, the default list shall be ignored and ps shall select the processes represented by the 
bitwise-inclusive OR of all the selection-criteria options. 

OPERANDS 

None. 


STDIN 

Not used. 

INPUT FILES 

None. 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of ps: 


COLUMNS Override the system-selected horizontal screen size, used to determine the number 
of text columns to display. See the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for valid values and 
results when it is unset or null. 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

LC_TIME Determine the format and contents of the date and time strings displayed. 

ASYNCHRONOUS EVENTS 
Default. 


STDOUT 

When the -o option is not specified, the standard output format is unspecified. 

xsi On XSI-conformant systems, the output format is as follows. The column headings and 
descriptions of the columns in a ps listing are given below. The precise meanings of these fields 
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30296 

30297 

30298 

30299 

30300 

30301 

30302 

30303 

30304 

30305 

30306 

30307 

30308 

30309 

30310 

30311 

30312 

30313 

30314 

30315 

30316 

30317 

30318 

30319 

30320 

30321 

30322 

30323 

30324 

30325 

30326 

30327 

30328 

30329 

30330 

30331 

30332 

30333 

30334 

30335 

30336 

30337 

30338 

30339 

30340 


Utilities 


ps 


are implementation-dependent. The letters ' f' and ' 1' (below) indicate the option (full or 
long) that shall cause the corresponding heading to appear; all means that the heading always 
appears. Note that these two options determine only what information is provided for a process; 
they do not determine which processes are listed. 


F 

(1) 

Flags (octal and additive) associated with the process. 

S 

(1) 

The state of the process. 

UID 

(f,l) 

The user ID number of the process owner; the login name is printed 
under the -f option. 

PID 

(all) 

The process ID of the process; it is possible to kill a process if this 
datum is known. 

PPID 

(U) 

The process ID of the parent process. 

C 

(U) 

Processor utilization for scheduling. 

PRI 

(1) 

The priority of the process; higher numbers mean lower priority. 

NI 

(1) 

Nice value; used in priority computation. 

ADDR 

(1) 

The address of the process. 

SZ 

(1) 

The size in blocks of the core image of the process. 

WCHAN 

(1) 

The event for which the process is waiting or sleeping; if blank, the 
process is running. 

STIME 

(f) 

Starting time of the process. 

TTY 

(all) 

The controlling terminal for the process. 

TIME 

(all) 

The cumulative execution time for the process. 

CMD 

(all) 

The command name; the full command name and its arguments are 
written under the -f option. 


A process that has exited and has a parent, but has not yet been waited for by the parent, is 
marked defunct. 

Under the option -f, ps tries to determine the command name and arguments given when the 
process was created by examining memory or the swap area. Failing this, the command name, as 
it would appear without the option -f, is written in square brackets. 

The -o option allows the output format to be specified under user control. 

The application shall ensure that the format specification is a list of names presented as a single I 
argument, <blank> or comma-separated. Each variable has a default header. The default header I 
can be overridden by appending an equals sign and the new text of the header. The rest of the 
characters in the argument shall be used as the header text. The fields specified shall be written 
in the order specified on the command line, and should be arranged in columns in the output. 
The field widths shall be selected by the system to be at least as wide as the header text (default 
or overridden value). If the header text is null, such as -o user=, the field width shall be at least 
as wide as the default header text. If all header text fields are null, no header line shall be 
written. 

The following names are recognized in the POSIX locale: 

ruser The real user ID of the process. This shall be the textual user ID, if it can be obtained 
and the field width permits, or a decimal representation otherwise. 

user The effective user ID of the process. This shall be the textual user ID, if it can be 
obtained and the field width permits, or a decimal representation otherwise. 

rgroup The real group ID of the process. This shall be the textual group ID, if it can be obtained 
and the field width permits, or a decimal representation otherwise. 
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30341 

30342 

group 

The effective group ID of the process. This shall be the textual group ID, if it can be 
obtained and the field width permits, or a decimal representation otherwise. 

30343 

pid 

The decimal value of the process ID. 

30344 

PPid 

The decimal value of the parent process ID. 

30345 

pgid 

The decimal value of the process group ID. 

30346 

30347 

30348 

pcpu 

The ratio of CPU time used recently to CPU time available in the same period, 
expressed as a percentage. The meaning of "recently" in this context is unspecified. The 
CPU time available is determined in an unspecified manner. 

30349 

vsz 

The size of the process in (virtual) memory in kilobytes as a decimal integer. 

30350 

nice 

The decimal value of the nice value of the process; see nice on page 698. 

30351 

etime 

In the POSIX locale, the elapsed time since the process was started, in the form: 

30352 


[[dd— ] hh:]mm:ss 

30353 

30354 

30355 


where dd shall represent the number of days, hh the number of hours, mm the number 
of minutes, and ss the number of seconds. The dd field shall be a decimal integer. The 
hh, mm, and ss fields shall be two-digit decimal integers padded on the left with zeros. 

30356 

time 

In the POSIX locale, the cumulative CPU time of the process in the form: 

30357 


[dd— ] hh:mm:ss 

30358 


The dd, hh, mm, and ss fields shall be as described in the etime specifier. 

30359 

30360 

tty 

The name of the controlling terminal of the process (if any) in the same format used by 
the zvho utility. 

30361 

comm 

The name of the command being executed (argv[ 0] value) as a string. 

30362 

30363 

30364 

30365 

30366 

30367 

30368 

args 

The command with all its arguments as a string. The implementation may truncate this 
value to the field width; it is implementation-dependent whether any further 
truncation occurs. It is unspecified whether the string represented is a version of the 
argument list as it was passed to the command when it started, or is a version of the 
arguments as they may have been modified by the application. Applications cannot 
depend on being able to modify their argument list and having that modification be 
reflected in the output of ps. 

30369 

30370 

Any field need not be meaningful in all implementations. In such a case a hyphen ) should 

be output in place of the field value. 

30371 

30372 

30373 

Only comm and args shall be allowed to contain <blank> characters; all others shall not. Any 
implementation-dependent variables shall be specified in the system documentation along with 
the default header and indicating if the field may contain <blank> characters. 

30374 

30375 

The following table specifies the default header to be used in the POSIX locale corresponding to 
each format specifier. 
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30376 

30377 

30378 

30379 

30380 

30381 

30382 

30383 

30384 

30385 

30386 

30387 

30388 

30389 

30390 

30391 

30392 

30393 

30394 

30395 

30396 

30397 

30398 

30399 

30400 

30401 

30402 

30403 

30404 

30405 

30406 

30407 

30408 

30409 

30410 

30411 

30412 

30413 

30414 

30415 

30416 

30417 


ps 


Table 4-17 Variable Names and Default Headers in ps 


Format Specifier 

Default Header 

Format Specifier 

Default Header 

args 

COMMAND 

ppid 

PPID 

comm 

COMMAND 

rgroup 

RGROUP 

etime 

ELAPSED 

ruser 

RUSER 

group 

GROUP 

time 

TIME 

nice 

NI 

tty 

TT 

pcpu 

%CPU 

user 

USER 

pgid 

PGID 

vsz 

VSZ 

pid 

PID 




STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Things can change while ps is running; the snapshot it gives is only true for an instant, and might 
not be accurate by the time it is displayed. 

The args format specifier is allowed to produce a truncated version of the command arguments. 
In some implementations, this information is no longer available when the ps utility is executed. 

If the field width is too narrow to display a textual ID, the system may use a numeric version. 
Normally, the system would be expected to choose large enough field widths, but if a large 
number of fields were selected to write, it might squeeze fields to their minimum sizes to fit on 
one line. One way to ensure adequate width for the textual IDs is to override the default header 
for a field to make it larger than most or all user or group names. 

There is no special quoting mechanism for header text. The header text is the rest of the 
argument. If multiple header changes are needed, multiple -o options can be used, such as: 

ps —o "user=User Name" —o pid=Process\ ID 

On some systems, especially multi-level secure systems, ps may be severely restricted and 
produce information only about child processes owned by the user. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

The command: 

ps —o user,pid,ppid=MOM —o args 
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30418 

30419 

30420 

30421 

30422 

30423 

30424 

30425 

30426 

30427 

30428 

30429 

30430 

30431 

30432 

30433 

30434 

30435 

30436 

30437 

30438 

30439 

30440 

30441 

30442 

30443 

30444 

30445 

30446 

30447 

30448 

30449 

30450 

30451 

30452 

30453 

30454 

30455 

30456 

30457 

30458 

30459 

30460 

30461 

30462 

30463 


ps 


Utilities 


writes at least the following in the POSIX locale: 

USER PID MOM COMMAND 

helene 34 12 ps —o uid,pid,ppid=MOM —o args 

The contents of the COMMAND field need not be the same in all implementations, due to 
possible truncation. 

RATIONALE 

There is very little commonality between BSD and System V implementations of ps. Many 
options conflict or have subtly different usages. The standard developers attempted to select a 
set of options that were useful on a wide range of systems and selected options that either can be 
implemented on both BSD and System V-based systems without breaking the current 
implementations or where the options are sufficiently similar that any changes would not be 
unduly problematic for users or implementors. 

It is recognized that on some systems, especially multi-level secure systems, ps may be nearly 
useless. The default output has therefore been chosen such that it does not break historical 
implementations and also is likely to provide at least some useful information on most systems. 

The major change is the addition of the format specification capability. The motivation for this 
invention is to provide a mechanism for users to access a wider range of system information, if 
the system permits it, in a portable manner. The fields chosen to appear in this volume of 
IEEE Std. 1003.1-200x were arrived at after considering what concepts were likely to be both 
reasonably useful to the "average" user and had a reasonable chance of being implemented on a 
wide range of systems. Again it is recognized that not all systems are able to provide all the 
information and, conversely, some may wish to provide more. It is hoped that the approach 
adopted will be sufficiently flexible and extensible to accommodate most systems. 
Implementations may be expected to introduce new format specifiers. 

The default output should consist of a short listing containing the process ID, terminal name, 
cumulative execution time, and command name of each process. 

The preference of the standard developers would have been to make the format specification an 
operand of the ps command. Unfortunately, BSD usage precluded this. 

At one time a format was included to display the environment array of the process. This was 
deleted because there is no portable way to display it. 

The -A option is equivalent to the BSD -g and the SVID -e. Because the two systems differed, a 
mnemonic compromise was selected. 

The -a option is described with some optional behavior because the SVID omits session leaders, 
but BSD does not. 

In an early proposal, format specifiers appeared for priority and start time. The former was not 
defined adequately in this volume of IEEE Std. 1003.1-200x and was removed in deference to the 
defined nice value; the latter because elapsed time was considered to be more useful. 

In a new BSD version of ps, a -O option can be used to write all of the default information, 
followed by additional format specifiers. This was not adopted because the default output is 
implementation-dependent. Nevertheless, this is a useful option that should be reserved for that 
purpose. In the -o option for the POSIX Shell and Utilities ps, the format is the concatenation of 
each -o. Therefore, the user can have an alias or function that defines the beginning of their 
desired format and add more fields to the end of the output in certain cases where that would be 
useful. 

The format of the terminal name is unspecified, but the descriptions of ps, talk, who, and write 
require that they all use the same format. 
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30464 The pcpu field indicates that the CPU time available is determined in an unspecified manner. 

30465 This is because it is difficult to express an algorithm that is useful across all possible machine 

30466 architectures. Historical counterparts to this value have attempted to show percentage of use in 

30467 the recent past, such as the preceding minute. Frequently, these values for all processes did not 

30468 add up to 100%. Implementations are encouraged to provide data in this field to users that will 

30469 help them identify processes currently affecting the performance of the system. 

30470 FUTURE DIRECTIONS 

30471 None. 

30472 SEE ALSO 

30473 kill , nice , renice 

30474 CHANGE HISTORY 

30475 First released in Issue 2. 

30476 Issue 4 

30477 Aligned with the ISO/IEC 9945-2:1993 standard. 

30478 Issue 6 

30479 This utility is now marked as part of the User Portability Utilities option. 

30480 The normative text is reworded to avoid use of the term "must” for application requirements. 
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30481 

30482 

30483 

30484 

30485 

30486 

30487 

30488 

30489 

30490 

30491 

30492 

30493 

30494 

30495 

30496 

30497 

30498 

30499 

30500 

30501 

30502 

30503 

30504 

30505 

30506 

30507 

30508 

30509 

30510 

30511 

30512 

30513 

30514 

30515 

30516 

30517 

30518 

30519 

30520 

30521 

30522 

30523 


NAME 

pwd — return working directory name 

SYNOPSIS 

pwd [-L | —P ] 

DESCRIPTION 

The pzvd utility shall write to standard output an absolute path name of the current working 
directory, which does not contain the file names dot or dot-dot. 

OPTIONS 

The pzvd utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following options shall be supported by the implementation: 

-L If the PWD environment variable contains an absolute path name of the current 

directory that does not contain the file names dot or dot-dot, pzvd shall write this 
path name to standard output. Otherwise, the -L option shall behave as the -P 
option. 

-P The absolute path name written shall not contain file names that, in the context of 

the path name, refer to files of type symbolic link. 

If both -L and -P are specified, the last one shall apply. If neither -L nor -P is specified, the pzvd 
utility shall behave as if -L had been specified. 

OPERANDS 

None. 


STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of pzvd: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PWD If the -P option is in effect, this variable shall be set to an absolute path name of 

the current working directory that does not contain any components that specify 
symbolic links, does not contain any components that are dot, and does not 
contain any components that are dot-dot. If an application sets or unsets the value 
of PWD, the behavior of pzvd is unspecified. 
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30524 ASYNCHRONOUS EVENTS 

30525 Default. 

30526 STDOUT 

30527 The pzvd utility output is an absolute path name of the current working directory: 

30528 "%s\n", <directory pathname> 

30529 STDERR 

30530 Used only for diagnostic messages. 

30531 OUTPUT FILES 

30532 None. 

30533 EXTENDED DESCRIPTION 

30534 None. 

30535 EXIT STATUS 

30536 The following exit values shall be returned: 

30537 0 Successful completion. 

30538 >0 An error occurred. 

30539 CONSEQUENCES OF ERRORS 

30540 If an error is detected, output shall not be written to standard output, a diagnostic message shall 

30541 be written to standard error, and the exit status is not zero. 

30542 APPLICATION USAGE 

30543 None. 

30544 EXAMPLES 

30545 None. 

30546 RATIONALE 

30547 Some implementations have historically provided pzvd as a shell special built-in command. 

30548 In most utilities, if an error occurs, partial output may be written to standard output. This does 

30549 not happen in historical implementations of pzvd. Because pzvd is frequently used in historical 

30550 shell scripts without checking the exit status, it is important that the historical behavior is 

30551 required here; therefore, the CONSEQUENCES OF ERRORS section specifically disallows any 

30552 partial output being written to standard output. 

30553 FUTURE DIRECTIONS 

30554 None. 

30555 SEE ALSO 

30556 cd, the System Interfaces volume of IEEE Std. 1003.1-200x, getczvd() 

30557 CHANGE HISTORY 

30558 First released in Issue 2. 

30559 Issue 4 

30560 Aligned with the ISO/IEC 9945-2:1993 standard. I 

30561 Issue 6 I 

30562 The -P and -L options are added to describe actions relating to symbolic links as specified in the I 

30563 IEEE P1003.2b draft standard. I 
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30564 NAME 

30565 qalter — alter batch job 

30566 SYNOPSIS 

30567 BE qalter [—a date_time ] [—A account_string ] [—c interval ] [—e path_name] 

30568 [—h hold_list ] [—j join_list ] [—k keep_list ] [-1 resource_list] 

30569 [—m mail_options ] [—M mail_list ] [—N name] [—o path_name] 

30570 [—p priority ] [—r y\n] [—S path_name_list] [—u user_list] 

30571 job_identifier . . . 

30572 


30573 DESCRIPTION 

30574 The attributes of a batch job are altered by a request to the batch server that manages the batch 

30575 job. The qalter utility is a user-accessible batch client that requests the alteration of the attributes 

30576 of one or more batch jobs. 

30577 The qalter utility shall alter the attributes of those batch jobs, and only those batch jobs, for which 

30578 a batch job_identifier is presented to the utility. 

30579 The qalter utility shall alter the attributes of batch jobs in the order in which the batch 

30580 job_identifiers are presented to the utility. 

30581 If the qalter utility fails to process a batch job_identifier successfully, the utility shall proceed to 

30582 process the remaining batch job_identifiers, if any. 

30583 For each batch job_identifier for which the qalter utility succeeds, each attribute of the identified 

30584 batch job shall be altered as indicated by all the options presented to the utility. 

30585 For each identified batch job for which the qalter utility fails, the utility shall not alter any 

30586 attribute of the batch job. 

30587 For each batch job that the qalter utility processes, the utility shall not modify any attribute other 

30588 than those required by the options and option-arguments presented to the utility. 

30589 The qalter utility shall alter batch jobs by sending a Modify Job Request to the batch server that 

30590 manages each batch job. At the time the qalter utility exits, it shall have modified the batch job 

30591 corresponding to each successfully processed batch job_identifier . An attempt to alter the 

30592 attributes of a batch job in the RUNNING state is implementation-dependent. 


30593 OPTIONS 

30594 The qalter utility shall conform to the System Interface Definitions volume of 

30595 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

30596 The following options shall be supported by the implementation: 

30597 -a date_time Redefine the time at which the batch job becomes eligible for execution. 


30598 The qalter utility shall accept an option-argument that conforms to the syntax of 

30599 the date_time operand of the touch utility. 


30600 

30601 

30602 

30603 

30604 

30605 

30606 


The qalter utility shall set the ExecutionJTime attribute of the batch job to the 
number of seconds since the Epoch that is equivalent to the local time expressed 
by the value of the date_time option-argument. Specifying a date_time option- 
argument that represents a time (number of seconds since the Epoch) earlier than 
the time at which the utility exits shall have the same effect on batch job execution 
as if the -a option had not been presented to the utility. The Epoch is defined in the 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.151, Epoch. 


30607 -A account _st ring 

30608 Redefine the account to which the resource consumption of the batch job should be 
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30609 

30610 

30611 

30612 

30613 

30614 

30615 

30616 

30617 

30618 

30619 

30620 

30621 

30622 

30623 

30624 

30625 

30626 

30627 

30628 

30629 

30630 

30631 

30632 

30633 

30634 

30635 

30636 

30637 

30638 

30639 

30640 

30641 

30642 

30643 

30644 

30645 

30646 

30647 

30648 

30649 

30650 

30651 

30652 


charged. 

The syntax of the account_string option-argument is unspecified. 

The qalter utility shall set the Account_Name attribute of the batch job to the value 
of the account_string option-argument. 

-c interval Redefine whether the batch job should be checkpointed, and if so, how often. 

The qalter utility shall accept a value for the interval option-argument that is one of 
the following: 

n No checkpointing is to be performed on the batch batch job 

(NCLCHECKPOINT). 

s Checkpointing is to be performed only when the batch server is shut 

down (CHECKPOINT.AT_SHUTDOWN). 

c Automatic periodic checkpointing is to be performed at the 

MinimumjCpuJnterval attribute of the batch queue, in units of CPU 
minutes (CHECKPOINT.AT_MIN_CPU_INTERVAL). 

c-minutes Automatic periodic checkpointing is to be performed every minutes 
of CPU time, or every MinimumjCpuJnterval minutes, whichever is 
greater. The minutes argument shall conform to the syntax for 
unsigned integers and shall be greater than zero. 

An implementation may define other checkpoint intervals. The conformance 
document for an implementation shall describe any alternative checkpoint 
intervals, how they are specified, their internal behavior, and how they affect the 
behavior of the utility. 

The qalter utility shall set the Checkpoint attribute of the batch job to the value of the 
interval option-argument. 

-e path_name Redefine the path to be used for the standard error stream of the batch job. 

The qalter utility shall accept a path_name option-argument that conforms to the 
syntax of the path_name element defined in the POSIX.1-1990 standard, which can 
be preceded by a host name element of the form hostname :. 

If the path_name option-argument constitutes an absolute path name, the qalter 
utility shall set the Error_Path attribute of the batch job to the value of the 
path_name option-argument, including the host name element, if present. 

If the path_name option-argument constitutes a relative path name and no host 
name element is specified, the qalter utility shall set the Error_Path attribute of the 
batch job to the value of the absolute path name derived by expanding the 
path_name option-argument relative to the current directory of the process that 
executes the qalter utility. 

If the path_name option-argument constitutes a relative path name and a host name 
element is specified, the qalter utility shall set the Error_Path attribute of the batch 
job to the value of the option-argument without expansion. 

If the path_name option-argument does not include a host name element, the qalter 
utility shall prefix the path name in the Error_Path attribute with hostname:, where 
hostname is the name of the host upon which the qalter utility is being executed. 

-h holdjist Redefine the types of holds, if any, on the batch job. The qalter -h option shall 
accept a value for the holdjist option-argument that is a string of alphanumeric 
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characters in the portable character set (see the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). 

The qalter utility shall accept a value for the hold_list option-argument that is a 
string of one or more of the characters ' u', ' s', or ' o', or the single character 
' n'. For each unique character in the hold_list option-argument, the qalter utility 
shall add a value to the Hold_Ti/pes attribute of the batch job as follows, each 
representing a different hold type: 

u USER 

s SYSTEM 

o OPERATOR 

If any of these characters are duplicated in the hold_list option-argument, the 
duplicates shall be ignored. An existing Hold_Ti/pes attribute can be cleared by the 
hold type: 

n NO_HOLD 

The qalter utility shall consider it an error if any hold type other than n is combined 
with hold type n. Strictly conforming applications shall not repeat any of the 
characters ' u', 's', ' o', or ' n' within the holdjist option-argument. The qalter 
utility shall permit the repetition of characters, but shall not assign additional 
meaning to the repeated characters. An implementation may define other hold 
types. The conformance document for an implementation shall describe any 
additional hold types, how they are specified, their internal behavior, and how 
they affect the behavior of the utility. 

-j joinjist Redefine which streams of the batch job are to be merged. The qalter -j option shall 
accept a value for the joinjist option-argument that is a string of alphanumeric 
characters in the portable character set (see the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). 

The qalter utility shall accept a join_list option-argument that consists of one or 
more of the characters ' e' and ' o', or the single character ' n'. 

All of the other batch job output streams specified shall be merged into the output 
stream represented by the character listed first in the joinjist option-argument. 

For each unique character in the joinjist option-argument, the qalter utility shall 
add a value to the Join_Path attribute of the batch job as follows, each representing 
a different batch job stream to join: 

e The standard error of the batch batch job (JOIN_STD_ERROR). 
o The standard output of the batch batch job (JOIN_STD_OUTPUT). 

An existing Join_Path attribute can be cleared by the join type: 
n NO JOIN 

If n is specified, then no files are joined. The qalter utility shall consider it an error if 
any join type other than n is combined with join type n. 

Strictly conforming applications shall not repeat any of the characters ' e', ' o', or 
' n' within the joinjist option-argument. The qalter utility shall permit the 
repetition of characters, but shall not assign additional meaning to the repeated 
characters. 
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An implementation may define other join types. The conformance document for an 
implementation shall describe any additional batch job streams, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. 

-k keepjist Redefine which output of the batch job to retain on the execution host. 

The qalter -k option shall accept a value for the keepjist option-argument that is a 
string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set). 

The qalter utility shall accept a keepjist option-argument that consists of one or 
more of the characters ' e' and ' o' or the single character ' n'. 

For each unique character in the keepjist option-argument, the qalter utility shall 
add a value to the Keep_Files attribute of the batch job as follows, each representing 
a different batch job stream to keep: 

e The standard error of the batch batch job (KEEP_STD_ERROR). 

o The standard output of the batch batch job (KEEP_STD_OUTPUT). 

If both 'e' and 'o' are specified, then both files are retained. An existing 
Keep_Files attribute can be cleared by the keep type: 

n NOJCEEP 

If n is specified, then no files are retained. The qalter utility shall consider it an error 
if any keep type other than n is combined with keep type n. 

Strictly conforming applications shall not repeat any of the characters ' e ', ' o ', or 
' n' within the keepjist option-argument. The qalter utility shall permit the 
repetition of characters, but shall not assign additional meaning to the repeated 
characters. An implementation may define other keep types. The conformance 
document for an implementation shall describe any additional keep types, how 
they are specified, their internal behavior, and how they affect the behavior of the 
utility. 

-1 resourceJist 

Redefine the resources that are allowed or required by the batch job. 

The qalter utility shall accept a resourcejist option-argument that conforms to the 
following syntax: 

resource=value[,,resource=value,,...] 

The qalter utility shall set one entry in the value of the Resource_List attribute of the 
batch job for each resource listed in the resourcejist option-argument. 

Because the list of supported resource names might vary by batch server, the qalter 
utility shall rely on the batch server to validate the resource names and associated 
values. See Section 3.3.3 on page 157 for a means of removing keyword =value (and 
value@keyword) pairs and other general rules for list-oriented batch job attributes. 

-m mailjoptions 

Redefine the points in the execution of the batch job at which the batch server is to 
send mail about a change in the state of the batch job. 

The qalter -m option shall accept a value for the mailjoptions option-argument that 
is a string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
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Character Set). 

The qalter utility shall accept a value for the mailjoptions option-argument that is a 
string of one or more of the characters ' e', ' b', and ' a', or the single character 
' n'. For each unique character in the mail_options option-argument, the qalter 
utility shall add a value to the Mailjilsers attribute of the batch job as follows, each 
representing a different time during the life of a batch job at which to send mail: 

e MAIL_AT_EXIT 

b MAIL_AT_BEGINNING 

a MAIL_AT_ABORT 

If any of these characters are duplicated in the mailjoptions option-argument, the 
duplicates shall be ignored. 

An existing Mail_Points attribute can be cleared by the mail type: 
n NO_MAIL 

If n is specified, then mail is not sent. The qalter utility shall consider it an error if 
any mail type other than n is combined with mail type n. Strictly conforming 
applications shall not repeat any of the characters ' e', ' b', ' a', or ' n' within 
the mailjoptions option-argument. The qalter utility shall permit the repetition of 
characters but shall not assign additional meaning to the repeated characters. 

An implementation may define other mail types. The conformance document for 
an implementation shall describe any additional mail types, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. 

-M mail_list Redefine the list of users to which the batch server that executes the batch job is to 
send mail, if the batch server sends mail about the batch job. 

The syntax of the mailjist option-argument is unspecified. If the implementation 
of the qalter utility uses a name service to locate users, the utility shall accept the 
syntax used by the name service. 

If the implementation of the qalter utility does not use a name service to locate 
users, the implementation shall accept the following syntax for user names: 

mail_address[,,mail_address,,...] 

The interpretation of mail_address is implementation-dependent. 

The qalter utility shall set the Mail_Users attribute of the batch job to the value of 
the mailjist option-argument. 

-N name Redefine the name of the batch job. 

The qalter -N option shall accept a value for the name option argument that is a 
string of up to 15 alphanumeric characters in the portable character set (see the 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set) where the first character is alphabetic. 

The syntax of the name option-argument is unspecified. 

The qalter utility shall set the JobJJame attribute of the batch job to the value of the 
name option-argument. 

-o path_name Redefine the path for the standard output of the batch job. 
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The qalter utility shall accept a path_name option-argument that conforms to the 
syntax of the path_name element defined in the POSIX.1-1990 standard, which can 
be preceded by a host name element of the form hostname:. 

If the path_name option-argument constitutes an absolute path name, the qalter 
utility shall set the Output_Path attribute of the batch job to the value of the 
path_name option-argument. 

If the path_name option-argument constitutes a relative path name and no host 
name element is specified, the qalter utility shall set the Output_Path attribute of the 
batch job to the absolute path name derived by expanding the path_name option- 
argument relative to the current directory of the process that executes the qalter 
utility. 

If the path_name option-argument constitutes a relative path name and a host name 
element is specified, the qalter utility shall set the Output_Path attribute of the batch 
job to option-argument without any expansion of the path name. 

If the path_name option-argument does not include a host name element, the qalter 
utility shall prefix the path name in the Output_Path attribute with hostname:, 
where hostname is the name of the host upon which the qalter utility is being 
executed. 

-p priority Redefine the priority of the batch job. 

The qalter utility shall accept a value for the priority option-argument that 
conforms to the syntax for signed decimal integers, and which is not less than 
-1024 and not greater than 1023. 

The qalter utility shall set the Priority attribute of the batch job to the value of the 
priority option-argument. 

—ry\n Redefine whether the batch job is rerunable. 

If the value of the option-argument is y, the qalter utility shall set the Rerunable 
attribute of the batch job to TRUE. 

If the value of the option-argument is n, the qalter utility shall set the Rerunable 
attribute of the batch job to FALSE. 

The qalter utility shall consider it an error if any character other than ' y' or ' n' is 
specified in the option-argument. 

-S path_name_list 

Redefine the shell that interprets the script at the destination system. 

The qalter utility shall accept a path_name_list option-argument that conforms to 
the following syntax: 

pathname[@host][,,pathname[@host 

The qalter utility shall accept only one path name that is missing a corresponding 
host name. The qalter utility shall allow only one path name per named host. 

The qalter utility shall add a value to the Shell_Path_List attribute of the batch job 
for each entry in the path_name_list option-argument. See Section 3.3.3 on page 157 
for a means of removing keyword-value (and valne@keyzvord) pairs and other 
general rules for list-oriented batch job attributes. 

-u user_list Redefine the user name under which the batch job is to run at the destination 
system. 
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The qalter utility shall accept a userjist option-argument that conforms to the 
following syntax: 

username[@host][,,username[@host] 

The qalter utility shall accept only one user name that is missing a corresponding 
host name. The qalter utility shall accept only one user name per named host. 

The qalter utility shall add a value to the User_List attribute of the batch job for each 
entry in the nser_list option-argument. See Section 3.3.3 on page 157 for a means of 
removing keyword-value (and valne@keyivord) pairs and other general rules for 
list-oriented batch job attributes. 

OPERANDS 

The qalter utility shall accept one or more operands that conform to the syntax for a batch 
jobjdentifier (see Section 3.3.1 on page 156). 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of qalter: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

Determine the format and contents of date and time strings written by qalter. 
Determine the login name of the user. 

Determine the timezone in which the time and date are written. If the TZ variable 
is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

None. 

STDERR 

Used only for diagnostic messages. 


LC_TIME 

LOGNAME 

TZ 
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30866 OUTPUT FILES 

30867 None. 

30868 EXTENDED DESCRIPTION 

30869 None. 

30870 EXIT STATUS 

30871 The following exit values shall be returned: 

30872 0 Successful completion. 

30873 >0 An error occurred. 

30874 CONSEQUENCES OF ERRORS 

30875 In addition to the default behavior, the qalter utility shall not be required to write a diagnostic 

30876 message to standard error when the error reply received from a batch server indicates that the 

30877 batch job_identifier does not exist on the server. Whether or not the qalter utility attempts to 

30878 locate the batch job on other batch servers is implementation-dependent. 

30879 APPLICATION USAGE 

30880 None. 

30881 EXAMPLES 

30882 None. 

30883 RATIONALE 

30884 The qalter utility allows users to change the attributes of a batch job. 

30885 As a means of altering a queued job, the qalter utility is superior to deleting and requeuing the 

30886 batch job insofar as an altered job retains its place in the queue with some traditional selection 

30887 algorithms. In addition, the qalter utility is both shorter and simpler than a sequence of qdel and 

30888 qsub utilities. 

30889 The result of an attempt on the part of a user to alter a batch job in a RUNNING state is 

30890 implementation-dependent because a batch job in the RUNNING state will already have opened 

30891 its output files and otherwise performed any actions indicated by the options in effect at the 

30892 time the batch job began execution. 

30893 The options processed by the qalter utility are identical to those of the qsub utility, with a few 

30894 exceptions: -V, -v, and -q. The -V and -v are inappropriate for the qalter utility, since they 

30895 capture potentially transient environment information from the submitting process. The -q 

30896 option would specify a new queue, which would largely negate the previously stated advantage 

30897 of using qalter ; furthermore, the qmove utility provides a superior means of moving jobs. 

30898 Each of the following paragraphs provides the rationale for a qalter option. 

30899 Additional rationale concerning these options can be found in the rationale for the qsub utility. 

30900 The -a option allows users to alter the date and time at which a batch job becomes eligible to 

30901 run. 

30902 The -A option allows users to change the account that will be charged for the resources 

30903 consumed by the batch job. Support for the -A option is mandatory for conforming 

30904 implementations of qalter, even though support of accounting is optional for servers. Whether or 

30905 not to support accounting is left to the implementor of the server, but mandatory support of the 

30906 -A option assures users of a consistent interface and allows them to control accounting on 

30907 servers that support accounting. 

30908 The -c option allows users to alter the checkpointing interval of a batch job. A checkpointing 

30909 system, which is not defined by IEEE Std. 1003.1-200x, allows recovery of a batch job at the most 
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30910 recent checkpoint in the event of a crash. Checkpointing is typically used for jobs that consume 

30911 expensive computing time or must meet a critical schedule. Users should be allowed to make 

30912 the tradeoff between the overhead of checkpointing and the risk to the timely completion of the 

30913 batch job; therefore, this volume of IEEE Std. 1003.1-200x provides the checkpointing interval 

30914 option. Support for checkpointing is optional for servers. 

30915 The -e option allows users to alter the name and location of the standard error stream written by 

30916 a batch job. However, the path of the standard error stream is meaningless if the value of the 

30917 Join_Path attribute of the batch job is TRUE. 

30918 The -h option allows users to set the hold type in the Hold_Types attribute of a batch job. The 

30919 qhold and qrls utilities add or remove hold types to the Hold_Types attribute, respectively. The -h 

30920 option has been modified to allow for implementation-dependent hold types. 

30921 The -j option allows users to alter the decision to join (merge) the standard error stream of the 

30922 batch job with the standard output stream of the batch job. 

30923 The -1 option allows users to change the resource limits imposed on a batch job. 

30924 The -m option allows users to modify the list of points in the life of a batch job at which the 

30925 designated users will receive mail notification. 

30926 The -M option allows users to alter the list of users who will receive notification about events in 

30927 the life of a batch job. 

30928 The -N option allows users to change the name of a batch job. 

30929 The -o option allows users to alter the name and path to which the standard output stream of 

30930 the batch job will be written. 

30931 The -P option allows users to modify the priority of a batch job. Support for priority is optional 

30932 for batch servers. 

30933 The -r option allows users to alter the rerunability status of a batch job. 

30934 The -S option allows users to change the name and location of the shell image that will be 

30935 invoked to interpret the script of the batch job. This option has been modified to allow a list of 

30936 shell name and locations associated with different host. 

30937 The -u option allows users to change the user identifier under which the batch job will execute. 

30938 As with other batch utilities, implementors can extend the qalter utility using the -W option. 

30939 The job_identifier operand syntax is provided so that the user can differentiate between the 

30940 originating and destination (or executing) batch server. These may or may not be the same. The 

30941 .server_name portion identifies the originating batch server, while the ©server portion identifies 

30942 the destination batch server. 

30943 Historically, the qalter utility has been a component of the Network Queuing System (NQS), the 

30944 existing practice from which this utility has been derived. 

30945 FUTURE DIRECTIONS 

30946 None. 

30947 SEE ALSO 

30948 qdel, qhold, qmove, qrls, qsub, touch, Chapter 3 on page 133 

30949 CHANGE HISTORY 

30950 Derived from IEEE Std. 1003.2d-1994. 
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30951 NAME 

30952 qdel — delete batch jobs 

30953 SYNOPSIS 

30954 BE qdel job_identifier . . . 

30955 

30956 DESCRIPTION 

30957 A batch job is deleted by sending a request to the batch server that manages the batch job. A 

30958 batch job that has been deleted is no longer subject to management by batch services. 

30959 The qdel utility is a user-accessible client of batch services that requests the deletion of one or 

30960 more batch jobs. 

30961 The qdel utility shall request a batch server to delete those batch jobs for which a batch 

30962 job_identifier is presented to the utility. 

30963 The qdel utility shall delete batch jobs in the order in which their batch job_identifiers are 

30964 presented to the utility. 

30965 If the qdel utility fails to process any batch job_identifier successfully, the utility shall proceed to 

30966 process the remaining batch job_identifier s, if any. 

30967 The qdel utility shall delete each batch job by sending a Delete Job Request to the batch server that 

30968 manages the batch job. 

30969 The qdel utility shall not exit until the batch job corresponding to each successfully processed 

30970 batch job_identifier has been deleted. 

30971 OPTIONS 

30972 None. 

30973 OPERANDS 

30974 The qdel utility shall accept one or more operands that conform to the syntax for a batch 

30975 job_identifier (see Section 3.3.1 on page 156). 

30976 STDIN 

30977 Not used. 

30978 INPUT FILES 

30979 None. 


30980 ENVIRONMENT VARIABLES 

30981 The following environment variables shall affect the execution of qdel: 


30982 

30983 

30984 

30985 

30986 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


30987 LC_ALL If set to a non-empty string value, override the values of all the other 

30988 internationalization variables. 


30989 

30990 

30991 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


30992 LC_MESSAGES 

30993 Determine the locale that should be used to affect the format and contents of 

30994 diagnostic messages written to standard error. 
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30995 LCJTIME Determine the format and contents of date and time strings written by qdel. 

30996 LOGNAME Determine the login name of the user. 

30997 TZ Determine the timezone in which the time and date are written. If the TZ variable 

30998 is not set, an unspecified system default timezone is used. 

30999 ASYNCHRONOUS EVENTS 

31000 Default. 

31001 STDOUT 

31002 An implementation of the qdel utility may write informative messages to standard output. 

31003 STDERR 

31004 Used only for diagnostic messages. 

31005 OUTPUT FILES 

31006 None. 

31007 EXTENDED DESCRIPTION 

31008 None. 

31009 EXIT STATUS 

31010 The following exit values shall be returned: 

31011 0 Successful completion. 

31012 >0 An error occurred. 

31013 CONSEQUENCES OF ERRORS 

31014 In addition to the default behavior, the qdel utility shall not be required to write a diagnostic 

31015 message to standard error when the error reply received from a batch server indicates that the 

31016 batch job_identifier does not exist on the server. Whether or not the qdel utility waits to output the 

31017 diagnostic message while attempting to locate the job on other servers is implementation- 

31018 dependent. 

31019 APPLICATION USAGE 

31020 None. 

31021 EXAMPLES 

31022 None. 

31023 RATIONALE 

31024 The qdel utility allows users and administrators to delete jobs. 

31025 The qdel utility provides functionality that is not otherwise available. For example, the kill utility 

31026 of the operating system does not suffice. First, to use the kill utility, the user might have to log in 

31027 on a remote node, because the kill utility does not operate across the network. Second, unlike 

31028 qdel, kill cannot remove jobs from queues. Lastly, the arguments of the qdel utility are job 

31029 identifiers rather than process identifiers, and so this utility can be passed the output of the 

31030 qselect utility, thus providing users with a means of deleting a list of jobs. 

31031 Because a set of jobs can be selected using the qselect utility, the qdel utility has not been 

31032 complicated with options that provide for selection of jobs. Instead, the batch jobs to be deleted 

31033 are identified individually by their job identifiers. 

31034 Historically, the qdel utility has been a component of NQS, the existing practice on which it is 

31035 based. However, the qdel utility defined in this volume of IEEE Std. 1003.1-200x does not provide 

31036 an option for specifying a signal number to send to the batch job prior to the killing of the 

31037 process; that capability has been subsumed by the qsig utility. 
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31038 A discussion was held about the delays of networking and the possibility that the batch server 

31039 may never respond, due to a down router, down batch server, or other network mishap. The 

31040 DESCRIPTION records this under the words "fails to process any job identifier". In the broad 

31041 sense, the network problem is also an error, which causes the failure to process the batch job 

31042 identifier. 

31043 As with other batch utilities, implementors can extend the qdel utility using the -W option. 

31044 FUTURE DIRECTIONS 

31045 None. 

31046 SEE ALSO 

31047 kill, qselect, qsig, Chapter 3 on page 133 

31048 CHANGE HISTORY 

31049 Derived from IEEE Std. 1003.2d-1994. 
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31050 NAME 

31051 qhold — hold batch jobs 

31052 SYNOPSIS 

31053 BE qhold [—h hold_lis t] job_identifier . . . 

31054 


31055 DESCRIPTION 

31056 A hold is placed on a batch job by a request to the batch server that manages the batch job. A 

31057 batch job that has one or more holds is not eligible for execution. The qhold utility is a user- 

31058 accessible client of batch services that requests one or more types of hold to be placed on one or 

31059 more batch jobs. 

31060 The qhold utility shall place holds on those batch jobs for which a batch job_identifier is presented 

31061 to the utility. 

31062 The qhold utility shall place holds on batch jobs in the order in which their batch job_identifiers 

31063 are presented to the utility. If the qhold utility fails to process any batch job-identifier successfully, 

31064 the utility shall proceed to process the remaining batch job-identifiers, if any. 

31065 The qhold utility shall place holds on each batch job by sending a Hold Job Request to the batch 

31066 server that manages the batch job. 

31067 The qhold utility shall not exit until holds have been placed on the batch job corresponding to 

31068 each successfully processed batch job-identifier. 


31069 OPTIONS 


31070 

31071 

31072 

31073 

31074 

31075 

31076 

31077 

31078 

31079 

31080 

31081 

31082 

31083 

31084 

31085 

31086 

31087 

31088 

31089 

31090 

31091 

31092 


The qhold utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following option shall be supported by the implementation: 

-h hold_list Define the types of holds to be placed on the batch job. 

The qhold -h option shall accept a value for the hold_list option-argument that is a 
string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set). 

The qhold utility shall accept a value for the hold_list option-argument that is a 
string of one or more of the characters ' u', ' s', or ' o', or the single character 
' n'. 

For each unique character in the hold_list option-argument, the qhold utility shall 
add a value to the Hold_Types attribute of the batch job as follows, each 
representing a different hold type: 

u USER 

s SYSTEM 

o OPERATOR 

If any of these characters are duplicated in the hold_list option-argument, the 
duplicates shall be ignored. 

An existing Hold_Types attribute can be cleared by the following hold type: 
n NO_HOLD 

The qhold utility shall consider it an error if any hold type other than n is combined 
with hold type n. 
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31093 Strictly conforming applications shall not repeat any of the characters ' u' , 's', 

31094 ' o' , or ' n' within the hold_list option-argument. The qhold utility shall permit the 

31095 repetition of characters, but shall not assign additional meaning to the repeated 

31096 characters. 

31097 An implementation may define other hold types. The conformance document for 

31098 an implementation shall describe any additional hold types, how they are 

31099 specified, their internal behavior, and how they affect the behavior of the utility. 

31100 If the -h option is not presented to the qhold utility, the implementation shall set 

31101 the Hold_Types attribute to USER. 

31102 OPERANDS 

31103 The qhold utility shall accept one or more operands that conform to the syntax for a batch 

31104 job_identifier (see Section 3.3.1 on page 156). 


31105 STDIN 


Not used. 


31107 INPUT FILES 

31108 None. 

31109 ENVIRONMENT VARIABLES 

31110 The following environment variables shall affect the execution of qhold: 

31111 LANG Provide a default value for the internationalization variables that are unset or null. 

31112 If LANG is unset or null, the corresponding value from the implementation- 

31113 dependent default locale shall be used. If any of the internationalization variables 

31114 contains an invalid setting, the utility shall behave as if none of the variables had 

31115 been defined. 

31116 LC_ALL If set to a non-empty string value, override the values of all the other 

31117 internationalization variables. 

31118 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

31119 characters (for example, single-byte as opposed to multi-byte characters in 

31120 arguments). 

31121 LCJAESSAGES 

31122 Determine the locale that should be used to affect the format and contents of 

31123 diagnostic messages written to standard error. 

31124 LC_TIME Determine the format and contents of date and time strings written by qhold. 

31125 LOGNAME Determine the login name of the user. 

31126 TZ Determine the timezone in which the time and date are written. If the TZ variable 

31127 is not set, an unspecified system default timezone is used. 

31128 ASYNCHRONOUS EVENTS 

31129 Default. 

31130 STDOUT 

31131 None. 


31132 STDERR 


Used only for diagnostic messages. 
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31134 OUTPUT FILES 

31135 None. 

31136 EXTENDED DESCRIPTION 

31137 None. 

31138 EXIT STATUS 

31139 The following exit values shall be returned: 

31140 0 Successful completion. 

31141 >0 An error occurred. 

31142 CONSEQUENCES OF ERRORS 

31143 In addition to the default behavior, the qhold utility shall not be required to write a diagnostic 

31144 message to standard error when the error reply received from a batch server indicates that the 

31145 batch job_identifier does not exist on the server. Whether or not the qhold utility waits to output 

31146 the diagnostic message while attempting to locate the job on other servers is implementation- 

31147 dependent. 

31148 APPLICATION USAGE 

31149 None. 

31150 EXAMPLES 

31151 None. 

31152 RATIONALE 

31153 The qhold utility allows users to place a hold on one or more jobs. A hold makes a batch job 

31154 ineligible for execution. 

31155 The qhold utility has options that allow the user to specify the type of hold. Should the user wish 

31156 to place a hold on a set of jobs that meet a selection criteria, such a list of jobs can be acquired 

31157 using the qselect utility. 

31158 The -h option allows the user to specify the type of hold that is to be placed on the job. This 

31159 option allows for USER, SYSTEM, OPERATOR, and implementation-dependent hold types. The 

31160 USER and OPERATOR holds are distinct. The batch server that manages the batch job will verify 

31161 that the user is authorized to set the specified hold for the batch job. 

31162 Mail is not required on hold because the administrator has the tools and libraries to build this 

31163 option if he or she wishes. 

31164 As with other batch utilities, implementors may extend the qhold utility using the -W option. 

31165 Historically, the qhold utility has been a part of some existing batch systems, although it has not 

31166 traditionally been a part of the NQS. 

31167 FUTURE DIRECTIONS 

31168 None. 

31169 SEE ALSO 

31170 qselect, Chapter 3 on page 133 

31171 CHANGE HISTORY 

31172 Derived from IEEE Std. 1003.2d-1994. 
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31173 NAME 

31174 qmove — move batch jobs 

31175 SYNOPSIS 

31176 BE qmove destination job_identifier . . . 

31177 

31178 DESCRIPTION 

31179 To move a batch job is to remove the batch job from the batch queue in which it resides and 

31180 instantiate the batch job in another batch queue. A batch job is moved by a request to the batch 

31181 server that manages the batch job. The qmove utility is a user-accessible batch client that requests 

31182 the movement of one or more batch jobs. 

31183 The qmove utility shall move those batch jobs, and only those batch jobs, for which a batch 

31184 job identifier is presented to the utility. 

31185 The qmove utility shall move batch jobs in the order in which the corresponding batch 

31186 job identifiers are presented to the utility. 

31187 If the qmove utility fails to process a batch job_identifier successfully, the utility shall proceed to 

31188 process the remaining batch job_identifiers, if any. 

31189 The qmove utility shall move batch jobs by sending a Move Job Request to the batch server that 

31190 manages each batch job. The qmove utility shall not exit before the batch jobs corresponding to all 

31191 successfully processed batch job_identifier s have been moved. 

31192 OPTIONS 

31193 None. 

31194 OPERANDS 

31195 The qmove utility shall accept one operand that conforms to the syntax for a destination (see 

31196 Section 3.3.2 on page 157). 

31197 The qmove utility shall accept one or more operands that conform to the syntax for a batch 

31198 jobjdentifier (see Section 3.3.1 on page 156). 

31199 STDIN 

31200 Not used. 

31201 INPUT FILES 

31202 None. 


31203 ENVIRONMENT VARIABLES 

31204 The following environment variables shall affect the execution of qmove: 


31205 

31206 

31207 

31208 

31209 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


31210 LC_ALL If set to a non-empty string value, override the values of all the other 

31211 internationalization variables. 


31212 

31213 

31214 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


31215 LC_MESSAGES 

31216 Determine the locale that should be used to affect the format and contents of 
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31217 

31218 

31219 

31220 

31221 

31222 

31223 

31224 

31225 

31226 

31227 

31228 

31229 

31230 

31231 

31232 

31233 

31234 

31235 

31236 

31237 

31238 

31239 

31240 

31241 

31242 

31243 

31244 

31245 

31246 

31247 

31248 

31249 

31250 

31251 

31252 

31253 

31254 

31255 

31256 

31257 


diagnostic messages written to standard error. 

LC_TIME Determine the format and contents of date and time strings written by qmove. 
LOGNAME Determine the login name of the user. 

TZ Determine the timezone in which the time and date are written. If the TZ variable 

is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

None. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

In addition to the default behavior, the qmove utility shall not be required to write a diagnostic 
message to standard error when the error reply received from a batch server indicates that the 
batch job_identifier does not exist on the server. Whether or not the qmove utility waits to output 
the diagnostic message while attempting to locate the job on other servers is implementation- 
dependent. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

The qmove utility allows users to move jobs between queues. 

The alternative to using the qmove utility—deleting the batch job and requeuing it—entails 
considerably more typing. 

Since the means of selecting jobs based on attributes has been encapsulated in the qselect utility, 
the only option of the qmove utility concerns authorization. The -u option provides the user with 
the convenience of changing the user identifier under which the batch job will execute. 
Minimalism and consistency has taken precedence over convenience; the -u option has been 
deleted because the equivalent capability exists with the -u option of the qalter utility. 

As with other batch utilities, implementors can extend the qmove utility using the -W option. 

The qmove utility is new, vis-a-vis existing practice; it has been defined in this volume of 
IEEE Std. 1003.1-200x as a logical extension of existing practice. 
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31258 FUTURE DIRECTIONS 

31259 None. 

31260 SEE ALSO 

31261 qalter, qselect, Chapter 3 on page 133 

31262 CHANGE HISTORY 

31263 Derived from IEEE Std. 1003.2d-1994. 
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31264 NAME 

31265 qmsg — send message to batch jobs 

31266 SYNOPSIS 

31267 BE qmsg [—E] [— 0 ] message_string job_identifier . . . 

31268 

31269 DESCRIPTION 

31270 To send a message to a batch job is to request that a server write a message string into one or 

31271 more output files of the batch job. A message is sent to a batch job by a request to the batch 

31272 server that manages the batch job. The qmsg utility is a user-accessible batch client that requests 

31273 the sending of messages to one or more batch jobs. 

31274 The qmsg utility shall write messages into the files of batch jobs by sending a Job Message Request 

31275 to the batch server that manages the batch job. The qmsg utility shall not directly write the 

31276 message into the files of the batch job. 

31277 The qmsg utility shall send a Job Message Request for those batch jobs, and only those batch jobs, 

31278 for which a batch job_identifier is presented to the utility. 

31279 The qmsg utility shall send Job Message Requests for batch jobs in the order in which their batch 

31280 job identifiers are presented to the utility. 

31281 If the qmsg utility fails to process any batch job_identifier successfully, the utility shall proceed to 

31282 process the remaining batch job_identifier s, if any. 

31283 The qmsg utility shall not exit before a Job Message Request has been sent to the server that 

31284 manages the batch job that corresponds to each successfully processed batch job identifier. 

31285 OPTIONS 

31286 The qmsg utility shall conform to the System Interface Definitions volume of 

31287 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

31288 The following options shall be supported by the implementation: 

31289 -E Specify that the message is written to the standard error of each batch job. 

31290 The qmsg utility shall write the message into the standard error of the batch job. 

31291 -O Specify that the message is written to the standard output of each batch job. 

31292 The qmsg utility shall write the message into the standard output of the batch job. 

31293 If neither the -O nor the -E option is presented to the qmsg utility, the utility shall write the 

31294 message into an implementation-dependent file. The conformance document for the 

31295 implementation shall describe the name and location of the implementation-dependent file. If 

31296 both the -O and the -E options are presented to the qmsg utility, then the utility shall write the 

31297 messages to both standard output and standard error. 

31298 OPERANDS 

31299 The qmsg utility shall accept a minimum of two operands, message_string and one or more batch 

31300 job identifiers. 

31301 The message_string operand shall be the string to be written to one or more output files of the 

31302 batch job followed by a <newline>. If the string contains <blank>s, then the string must be 

31303 quoted. The message_string shall be encoded in the portable character set (see the System 

31304 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). 

31305 All remaining operands are batch job identifiers that conform to the syntax for a batch 

31306 job_identifier (see Section 3.3.1 on page 156). 


814 


Technical Standard (2000) (Draft February 29, 2000) 




Utilities 


qmsg 


31307 

31308 

31309 

31310 

31311 

31312 

31313 

31314 

31315 

31316 

31317 

31318 

31319 

31320 

31321 

31322 

31323 

31324 

31325 

31326 

31327 

31328 

31329 

31330 

31331 

31332 

31333 

31334 

31335 

31336 

31337 

31338 

31339 

31340 

31341 

31342 

31343 

31344 

31345 

31346 

31347 

31348 

31349 


STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of qmsg: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

Determine the format and contents of date and time strings written by qmsg. 
Determine the login name of the user. 

Determine the timezone in which the time and date are written. If the TZ variable 
is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

None. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

In addition to the default behavior, the qmsg utility shall not be required to write a diagnostic 
message to standard error when the error reply received from a batch server indicates that the 
batch job_identifier does not exist on the server. Whether or not the qmsg utility waits to output 
the diagnostic message while attempting to locate the job on other servers is implementation- 
dependent. 


LC_TIME 

LOGNAME 

TZ 
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31350 APPLICATION USAGE 

31351 None. 

31352 EXAMPLES 

31353 None. 

31354 RATIONALE 

31355 The qmsg utility allows users to write messages into the output files of running jobs. Users, 

31356 including operators and administrators, have a number of occasions when they want to place 

31357 messages in the output files of a batch job. For example, if a disk that is being used by a batch job 

31358 is showing errors, the operator might note this in the standard error stream of the batch job. 

31359 The options of the qmsg utility provide users with the means of placing the message in the 

31360 output stream of their choice. The default output stream for the message—if the user does not 

31361 designate an output stream—is implementation-dependent, since many implementations will 

31362 provide, as an extension to this volume of IEEE Std. 1003.1-200x, a log file that shows the history 

31363 of utility execution. 

31364 If users wish to send a message to a set of jobs that meet a selection criteria, the qselect utility can 

31365 be used to acquire the appropriate list of job identifiers. 

31366 The -E option allows users to place the message in the standard error stream of the batch job. 

31367 The -O option allows users to place the message in the standard output stream of the batch job. 

31368 As with other batch utilities, implementors may extend the qmsg utility using to the -W option. 

31369 Historically, the qmsg utility is an existing practice in the offerings of one or more implementors 

31370 of an NQS-derived batch system. The utility has been found to be useful enough that it deserves 

31371 to be included in this volume of IEEE Std. 1003.1-200x. 

31372 FUTURE DIRECTIONS 

31373 None. 

31374 SEE ALSO 

31375 qselect , Chapter 3 on page 133 

31376 CHANGE HISTORY 

31377 Derived from IEEE Std. 1003.2d-1994. 
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31378 NAME 

31379 qrerun — rerun batch jobs 

31380 SYNOPSIS 

31381 BE qrerun job_identifier . . . 

31382 

31383 DESCRIPTION 

31384 To rerun a batch job is to terminate the session leader of the batch job, delete any associated 

31385 checkpoint files, and return the batch job to the batch queued state. A batch job is rerun by a 

31386 request to the batch server that manages the batch job. The qrerun utility is a user-accessible 

31387 batch client that requests the rerunning of one or more batch jobs. 

31388 The qrerun utility shall rerun those batch jobs for which a batch job_identifier is presented to the 

31389 utility. 

31390 The qrerun utility shall rerun batch jobs in the order in which their batch job_identifier s are 

31391 presented to the utility. 

31392 If the qrerun utility fails to process any batch job_identifier successfully, the utility shall proceed 

31393 to process the remaining batch job_identifiers, if any. 

31394 The qrerun utility shall rerun batch jobs by sending a Rerun Job Request to the batch server that 

31395 manages each batch job. 

31396 For each successfully processed batch job_identifier , the qrerun utility shall have rerun the 

31397 corresponding batch batch job at the time the utility exits. 

31398 OPTIONS 

31399 None. 

31400 OPERANDS 

31401 The qrerun utility shall accept one or more operands that conform to the syntax for a batch 

31402 job_identifier (see Section 3.3.1 on page 156). 

31403 STDIN 

31404 Not used. 

31405 INPUT FILES 

31406 None. 


31407 ENVIRONMENT VARIABLES 

31408 The following environment variables shall affect the execution of qrerun: 


31409 

31410 

31411 

31412 

31413 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


31414 LC_ALL If set to a non-empty string value, override the values of all the other 

31415 internationalization variables. 


31416 

31417 

31418 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


31419 LC_MESSAGES 

31420 Determine the locale that should be used to affect the format and contents of 

31421 diagnostic messages written to standard error. 
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31422 

31423 

31424 

31425 

31426 

31427 

31428 

31429 

31430 

31431 

31432 

31433 

31434 

31435 

31436 

31437 

31438 

31439 

31440 

31441 

31442 

31443 

31444 

31445 

31446 

31447 

31448 

31449 

31450 

31451 

31452 

31453 

31454 

31455 

31456 

31457 

31458 

31459 

31460 


LC_TIME Determine the format and contents of date and time strings written by qrerun. 
LOGNAME Determine the login name of the user. 

TZ Determine the timezone in which the time and date are written. If the TZ variable 

is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

None. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

In addition to the default behavior, the qrerun utility shall not be required to write a diagnostic 
message to standard error when the error reply received from a batch server indicates that the 
batch job_identifier does not exist on the server. Whether or not the qrerun utility waits to output 
the diagnostic message while attempting to locate the job on other servers is implementation- 
dependent. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

The qrerun utility allows users to cause jobs in the running state to exit and rerun. 

As with other batch utilities, implementors may extend the qrerun utility using the -W option. 

The qrerun utility is a new utility, vis-a-vis existing practice, that has been defined in this volume 
of IEEE Std. 1003.1-200x to correct user-perceived deficiencies in the existing practice. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Chapter 3 on page 133 

CHANGE HISTORY 

Derived from IEEE Std. 1003.2d-1994. 
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31461 NAME 

31462 qrls — release batch jobs 

31463 SYNOPSIS 

31464 BE qrls [—h hold_list ] job_identifier . . . 

31465 


31466 DESCRIPTION 

31467 A batch job might have one or more holds, which prevent the batch job from executing. A batch 

31468 job from which all the holds have been removed becomes eligible for execution and is said to 

31469 have been released. A batch job hold is removed by sending a request to the batch server that 

31470 manages the batch job. The qrls utility is a user-accessible client of batch services that requests 

31471 holds be removed from one or more batch jobs. 

31472 The qrls utility shall remove one or more holds from those batch jobs for which a batch 

31473 job_identifier is presented to the utility. 

31474 The qrls utility shall remove holds from batch jobs in the order in which their batch job_identifier s 

31475 are presented to the utility. 

31476 If the qrls utility fails to process a batch job_identifier successfully, the utility shall proceed to 

31477 process the remaining batch job_identifiers, if any. 

31478 The qrls utility shall remove holds on each batch job by sending a Release Job Request to the batch 

31479 server that manages the batch job. 

31480 The qrls utility shall not exit until the holds have been removed from the batch job 

31481 corresponding to each successfully processed batch jobjdentifier. 

31482 OPTIONS 

31483 The qrls utility shall conform to the System Interface Definitions volume of 

31484 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

31485 The following option shall be supported by the implementation: 

31486 -h hold_list Define the types of holds to be removed from the batch job. 


31487 The qrls -h option shall accept a value for the holdjist option-argument that is a 

31488 string of alphanumeric characters in the portable character set (see the System 

31489 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 

31490 Character Set). 


31491 The qrls utility shall accept a value for the holdjist option-argument that is a string 

31492 of one or more of the characters ' u', ' s', or ' o', or the single character ' n'. 

31493 For each unique character in the holdjist option-argument, the qrls utility shall add 

31494 a value to the HoldJTypes attribute of the batch job as follows, each representing a 

31495 different hold type: 

31496 U USER 

31497 s SYSTEM 

31498 o OPERATOR 


31499 If any of these characters are duplicated in the holdjist option-argument, the 

31500 duplicates shall be ignored. 

31501 An existing HoldJTypes attribute can be cleared by the following hold type: 

31502 n NO_HOLD 
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31503 The qrls utility shall consider it an error if any hold type other than n is combined 

31504 with hold type n. 


31505 

31506 

31507 

31508 


Strictly conforming applications shall not repeat any of the characters ' u', 's', 
' o', or ' n' within the holdjist option-argument. The qrls utility shall permit the 
repetition of characters, but shall not assign additional meaning to the repeated 
characters. 


31509 

31510 

31511 


An implementation may define other hold types. The conformance document for 
an implementation shall describe any additional hold types, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. 


31512 If the -h option is not presented to the qrls utility, the implementation shall remove 

31513 the USER hold in the Hold_Types attribute. 


31514 OPERANDS 

31515 The qrls utility shall accept one or more operands that conform to the syntax for a batch 

31516 job_identifier (see Section 3.3.1 on page 156). 


31517 STDIN 

31518 Not used. 


31519 INPUT FILES 

31520 None. 


31521 ENVIRONMENT VARIABLES 

31522 The following environment variables shall affect the execution of qrls: 


31523 

31524 

31525 

31526 

31527 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


31528 LC_ALL If set to a non-empty string value, override the values of all the other 

31529 internationalization variables. 


31530 

31531 

31532 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


31533 

31534 

31535 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


31536 

31537 

31538 

31539 


LC_TIME 

LOGNAME 

TZ 


Determine the format and contents of date and time strings written by qrls. 
Determine the login name of the user. 

Determine the timezone in which the time and date are written. If the TZ variable 
is not set, an unspecified system default timezone is used. 


31540 ASYNCHRONOUS EVENTS 

31541 Default. 


31542 STDOUT 

31543 None. 
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31544 STDERR 

31545 Used only for diagnostic messages. 

31546 OUTPUT FILES 

31547 None. 

31548 EXTENDED DESCRIPTION 

31549 None. 

31550 EXIT STATUS 

31551 The following exit values shall be returned: 

31552 0 Successful completion. 

31553 >0 An error occurred. 

31554 CONSEQUENCES OF ERRORS 

31555 In addition to the default behavior, the qrls utility shall not be required to write a diagnostic 

31556 message to standard error when the error reply received from a batch server indicates that the 

31557 batch job_identifier does not exist on the server. Whether or not the qrls utility waits to output the 

31558 diagnostic message while attempting to locate the job on other servers is implementation- 

31559 dependent. 

31560 APPLICATION USAGE 

31561 None. 

31562 EXAMPLES 

31563 None. 

31564 RATIONALE 

31565 The qrls utility allows users, operators, and administrators to remove holds from jobs. 

31566 The qrls utility does not support any job selection options or wildcard arguments. Users may 

31567 acquire a list of jobs selected by attributes using the qselect utility. For example, a user could 

31568 select all of their held jobs. 

31569 The -h option allows the user to specify the type of hold that is to be removed. This option 

31570 allows for USER, SYSTEM, OPERATOR, and implementation-dependent hold types. The batch 

31571 server that manages the batch job will verify whether the user is authorized to remove the 

31572 specified hold for the batch job. If more than one type of hold has been placed on the batch job, a 

31573 user may wish to remove only some of them. 

31574 Mail is not required on release because the administrator has the tools and libraries to build this 

31575 option if required. 

31576 As with other batch utilities, implementors may extend the qrls utility by means of the -W 

31577 option. 

31578 The qrls utility is a new utility vis-a-vis existing practice; it has been defined in this volume of 

31579 IEEE Std. 1003.1-200x as the natural complement to the qhold utility. 

31580 FUTURE DIRECTIONS 

31581 None. 

31582 SEE ALSO 

31583 qhold, qselect, Chapter 3 on page 133 
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31584 CHANGE HISTORY 

31585 Derived from IEEE Std. 1003.2d-1994. 
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31586 NAME 

31587 qselect — select batch jobs 

31588 SYNOPSIS 

31589 BE 

31590 

31591 

31592 

31593 DESCRIPTION 

31594 To select a set of batch jobs is to return the batch job_identifiers for each batch job that meets a list 

31595 of selection criteria. A set of batch jobs is selected by a request to a batch server. The qselect 

31596 utility is a user-accessible batch client that requests the selection of batch jobs. 

31597 Upon successful completion, the qselect utility shall have returned a list of zero or more batch 

31598 job_identifiers that meet the criteria specified by the options and option-arguments presented to 

31599 the utility. 

31600 The qselect utility shall select batch jobs by sending a Select Jobs Request to a batch server. The 

31601 qselect utility shall not exit until the server replies to each request generated. 

31602 For each option presented to the qselect utility, the utility shall restrict the set of selected batch 

31603 jobs as described in the OPTIONS section. 

31604 The qselect utility shall not restrict selection of batch jobs except by authorization and as required 

31605 by the options presented to the utility. 

31606 When an option is specified with a mandatory or optional op component to the option- 

31607 argument, then op shall specify a relation between the value of a certain batch job attribute and 

31608 the value component of the option-argument. If an op is allowable on an option, then the 

31609 description of the option letter indicates the op as either mandatory or optional. Acceptable 

31610 strings for the op component, and the relation the string indicates, are shown in the following 


31611 

list: 


31612 

31613 

•eq. 

The value represented by the attribute of the batch job is equal to the value represented 
by the option-argument. 

31614 

31615 

. ge. 

The value represented by the attribute of the batch job is greater than or equal to the 
value represented by the option-argument. 

31616 

31617 

• gt • 

The value represented by the attribute of the batch job is greater than the value 
represented by the option-argument. 

31618 

31619 

. It. 

The value represented by the attribute of the batch job is less than the value 
represented by the option-argument. 

31620 

31621 

. le. 

The value represented by the attribute of the batch job is less than or equal to the value 
represented by the option-argument. 

31622 

31623 

. ne. 

The value represented by the attribute of the batch job is not equal to the value 
represented by the option-argument. 


31624 OPTIONS 

31625 The qselect utility shall conform to the System Interface Definitions volume of 

31626 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

31627 The following options shall be supported by the implementation: 

31628 -a [op]date_time 

31629 Restrict selection to a specific time, or a range of times. 


qselect [—a [ op]date_time] [—A account_string] [— c [op]interval] 
[— h hold_list] [—1 resource_list ][— N name] [—p [op]priority] 
[— q destination ] [—r yin][—s states] [— u user_list] 
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31630 

31631 

31632 

31633 

31634 

31635 

31636 

31637 

31638 

31639 

31640 

31641 

31642 

31643 

31644 

31645 

31646 

31647 

31648 

31649 

31650 

31651 

31652 

31653 

31654 

31655 

31656 

31657 

31658 

31659 

31660 

31661 

31662 

31663 

31664 

31665 

31666 

31667 

31668 

31669 

31670 

31671 

31672 

31673 


The qselect utility shall select only batch jobs for which the value of the 
Execution JTime attribute is related to the Epoch equivalent of the local time 
expressed by the value of the date_time component of the option-argument in the 
manner indicated by the value of the op component of the option-argument. 

The qselect utility shall accept a date_time component of the option-argument that 
conforms to the syntax of the date_time operand of the touch utility. 

If the op component of the option-argument is not presented to the qselect utility, 
the utility shall select batch jobs for which the Execution_Time attribute is equal to 
the date_time component of the option-argument. 

When comparing times, the qselect utility shall use the following definitions for the 
op component of the option-argument: 

. eq. The time represented by value of the Execution JTime attribute of the batch 
job is equal the time represented by the date_time component of the 
option-argument. 

. ge . The time represented by value of the Execution JTime attribute of the batch 
job is after or equal to the time represented by the date_time component of 
the option-argument. 

. gt. The time represented by value of the Execution JTime attribute of the batch 
job is after the time represented by the date_time component of the 
option-argument. 

. It. The time represented by value of the Execution JTime attribute of the batch 
job is before the time represented by the date_time component of the 
option-argument. 

. le . The time represented by value of the Execution JTime attribute of the batch 
job is before or equal to the time represented by the date_time component 
of the option-argument. 

. ne . The time represented by value of the Execution JTime attribute of the batch 
job is not equal to the time represented by the date_time component of the 
option-argument. 

The qselect utility shall accept the defined character strings for the op component of 
the option-argument. 

-A account_string 

Restrict selection to the batch jobs charging a specified account. 

The qselect utility shall select only batch jobs for which the value of the 
Account_Name attribute of the batch job matchs the value of the account_string 
option-argument. 

The syntax of the account_string option-argument is unspecified. 

-c [op]interval 

Restrict selection to batch jobs within a range of checkpoint intervals. 

The qselect utility shall select only batch jobs for which the value of the Checkpoint 
attribute relates to the value of the interval component of the option-argument in 
the manner indicated by the value of the op component of the option-argument. 

If the op component of the option-argument is omitted, the qselect utility shall 
select batch jobs for which the value of the Checkpoint attribute is equal to the value 
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31674 

31675 

31676 

31677 

31678 

31679 

31680 

31681 

31682 

31683 

31684 

31685 

31686 

31687 

31688 

31689 

31690 

31691 

31692 

31693 

31694 

31695 

31696 

31697 

31698 

31699 

31700 

31701 

31702 

31703 

31704 

31705 

31706 

31707 

31708 

31709 

31710 

31711 

31712 

31713 

31714 


of the interval component of the option-argument. 

When comparing checkpoint intervals, the qselect utility shall use the following 
definitions for the op component of the option-argument: 

. eq. The value of the Checkpoint attribute of the batch job equals the value of 
the interval component of the option-argument. 

. ge . The value of the Checkpoint attribute of the batch job is greater than or 
equal to the value of the interval component option-argument. 

. gt. The value of the Checkpoint attribute of the batch job is greater than the 
value of the interval component option-argument. 

. It. The value of the Checkpoint attribute of the batch job is less than the value 
of the interval component option-argument. 

. le . The value of the Checkpoint attribute of the batch job is less than or equal 
to the value of the interval component option-argument. 

. ne . The value of the Checkpoint attribute of the batch job does not equal the 
value of the interval component option-argument. 

The qselect utility shall accept the defined character strings for the op component of 
the option-argument. 

The ordering relationship for the values of the interval option-argument is defined 
to be: 

'n' .gt. 's' .gt. 'c =minutes' .ge. 'c' 

When comparing Checkpoint attributes with an interval having the value of the 
single character ' u', only equality or inequality are valid comparisons. 

-h hold_list Restrict selection to batch jobs that have a specific type of hold. 

The qselect utility shall select only batch jobs for which the value of the Hold_Types 
attribute matches the value of the holdjist option-argument. 

The qselect -h option shall accept a value for the holdjist option-argument that is a 
string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set). 

The qselect utility shall accept a value for the holdjist option-argument that is a 
string of one or more of the characters ' u', ' s', or ' o', or the single character 
' n'. 

Each unique character in the holdjist option-argument of the qselect utility is 
defined as follows, each representing a different hold type: 

u USER 

s SYSTEM 

o OPERATOR 

If any of these characters are duplicated in the holdjist option-argument, the 
duplicates shall be ignored. 

The qselect utility shall consider it an error if any hold type other than n is 
combined with hold type n. 
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31715 

31716 

31717 

31718 

31719 

31720 

31721 

31722 

31723 

31724 

31725 

31726 

31727 

31728 

31729 

31730 

31731 

31732 

31733 

31734 

31735 

31736 

31737 

31738 

31739 

31740 

31741 

31742 

31743 

31744 

31745 

31746 

31747 

31748 

31749 

31750 

31751 

31752 

31753 

31754 

31755 

31756 

31757 

31758 


Strictly conforming applications shall not repeat any of the characters ' u', 's', 
' o', or ' n' within the hold_list option-argument. The qselect utility shall permit 
the repetition of characters, but shall not assign additional meaning to the repeated 
characters. 

An implementation may define other hold types. The conformance document for 
an implementation shall describe any additional hold types, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. 

-1 resourceJist 

Restrict selection to batch jobs with specified resource limits and attributes. 

The qselect utility shall accept a resourcejist option-argument with the following 
syntax: 

resource_name op value [,, resource_name op value,, ...] 

When comparing resource values, the qselect utility shall use the following 
definitions for the op component of the option-argument: 

. eq. The value of the resource of the same name in the Resource_List attribute 
of the batch job equals the value of the value component of the option- 
argument. 

. ge . The value of the resource of the same name in the Resource_List attribute 
of the batch job is greater than or equal to the value of the value 
component of the option-argument. 

. gt. The value of the resource of the same name in the Resource_List attribute 
of the batch job is greater than the value of the value component of the 
option-argument. 

. It. The value of the resource of the same name in the Resource_List attribute 
of the batch job is less than the value of the value component of the 
option-argument. 

. ne . The value of the resource of the same name in the Resource_List attribute 
of the batch job does not equal the value of the value component of the 
option-argument. 

. le . The value of the resource of the same name in the Resource_List attribute 
of the batch job is less than or equal to the value of the value component 
of the option-argument. 

When comparing the limit of a Resource_List attribute with the value component of 
the option-argument, if the limit, the value, or both are non-numeric, only equality 
or inequality are valid comparisons. 

The qselect utility shall select only batch jobs for which the values of the 
resource_names listed in the resourcejist option-argument match the corresponding 
limits of the Resource_List attribute of the batch job. 

Limits of resource_name s present in the Resource_List attribute of the batch job that 
have no corresponding values in the resourcejist option-argument shall not be 
considered when selecting batch jobs. 

-N name Restrict selection to batch jobs with a specified name. 

The qselect utility shall select only batch jobs for which the value of the JobJJame 
attribute matches the value of the name option-argument. The string specified in 
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the name option-argument shall be passed, uninterpreted, to the server. This allows 
an implementation to match "wildcard" patterns against batch job names. 

An implementation shall describe in the conformance document the format it 
supports for matching against the Job_Name attribute. 

-p [op]priority 

Restrict selection to batch jobs of the specified priority or range of priorities. 

The qselect utility shall select only batch jobs for which the value of the Priority 
attribute of the batch job relates to the value of the priority component of the 
option-argument in the manner indicated by the value of the op component of the 
option-argument. 

If the op component of the option-argument is omitted, the qselect utility shall 
select batch jobs for which the value of the Priority attribute of the batch job is 
equal to the value of the priority component of the option-argument. 

When comparing priority values, the qselect utility shall use the following 
definitions for the op component of the option-argument: 

. eq. The value of the Priority attribute of the batch job equals the value of the 
priority component of the option-argument. 

. ge . The value of the Priority attribute of the batch job is greater than or equal 
to the value of the priority component option-argument. 

. gt. The value of the Priority attribute of the batch job is greater than the value 
of the priority component option-argument. 

. It. The value of the Priority attribute of the batch job is less than the value of 
the priority component option-argument. 

. It. The value of the Priority attribute of the batch job is less than or equal to 
the value of the priority component option-argument. 

. ne . The value of the Priority attribute of the batch job does not equal the value 
of the priority component option-argument. 

-q destination 

Restrict selection to the specified batch queue or server, or both. 

The qselect utility shall select only batch jobs that are located at the destination 
indicated by the value of the destination option-argument. 

The destination defines a batch queue, a server, or a batch queue at a server. 

The qselect utility shall accept an option-argument for the -q option that conforms 
to the syntax for a destination. If the -q option is not presented to the qselect utility, 
the utility shall select batch jobs from all batch queues at the default batch server. 

If the option-argument describes only a batch queue, the qselect utility shall select 
only batch jobs from the batch queue of the specified name at the default batch 
server. The means by which qselect determines the default server is 
implementation-dependent. 

If the option-argument describes only a batch server, the qselect utility shall select 
batch jobs from all the batch queues at that batch server. 

If the option-argument describes both a batch queue and a batch server, the qselect 
utility shall select only batch jobs from the specified batch queue at the specified 
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31802 


server. 

31803 

-rijln 

Restrict selection to batch jobs with the specified rerunability status. 

31804 

31805 


The qselect utility shall select only batch jobs for which the value of the Rerunable 
attribute of the batch job matches the value of the option-argument. 

31806 

31807 

31808 


The qselect utility shall accept a value for the option-argument that consists of 
either the single character ' y' or the single character ' n'. The character ' y' 
represents the value TRUE, and the character ' n' represents the value FALSE. 

31809 

-s states 

Restrict selection to batch jobs in the specified states. 

31810 

31811 


The qselect utility shall accept an option-argument that consists of any combination 
of the characters ' e', ' q', ' r', ' w', ' h', and ' t '. 

31812 

31813 

31814 


Conforming applications shall not repeat any character in the option-argument. 
The qselect utility shall permit the repetition of characters in the option-argument, 
but shall not assign additional meaning to repeated characters. 

31815 

31816 


The qselect utility shall interpret the characters in the states option-argument as 
follows: 

31817 


e Represents the EXITING state. 

31818 


q Represents the QUEUED state. 

31819 


r Represents the RUNNING state. 

31820 


t Represents the TRANSITING state. 

31821 


h Represents the HELD state. 

31822 


w Represents the WAITING state. 

31823 

31824 


For each character in the states option-argument, the qselect utility shall select batch 
jobs in the corresponding state. 

31825 

-u userjist 

Restrict selection to batch jobs owned by the specified user names. 

31826 

31827 


The qselect utility shall select only the batch jobs of those users specified in the 
userjist option-argument. 

31828 

31829 


The qselect utility shall accept a userjist option-argument that conforms to the 
following syntax: 

31830 


username [@host][,, username[@hos t],, ...] 

31831 

31832 


The qselect utility shall accept only one user name that is missing a corresponding 
host name. The qselect utility shall accept only one user name per named host. 

31833 OPERANDS 

31834 None. 


31835 STDIN 

31836 

Not used. 


31837 INPUT FILES 

31838 None. 
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31872 

31873 

31874 

31875 

31876 

31877 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of qselect: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

Determine the format and contents of date and time strings written by qselect. 
Determine the login name of the user. 

Determine the timezone in which the time and date are written. If the TZ variable 
is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The qselect utility shall write zero or more batch job_identifiers to standard output. 

The qselect utility shall separate the batch job_identifiers written to standard output by white 
space. 

The qselect utility shall write batch job_identifiers in the following format: 

sequence_number.server_name@server 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 


LC_TIME 

LOGNAME 

TZ 
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31878 APPLICATION USAGE 

31879 None. 

31880 EXAMPLES 

31881 The following example shows how a user might use the qselect utility in conjunction with the 

31882 qdel utility to delete all of his or her jobs in the queued state without affecting any jobs that are 

31883 already running: 

31884 qdel qselect — s q 

31885 or: 

31886 qselect — s q | | xargs qdel 

31887 RATIONALE 

31888 The qselect utility allows users to acquire a list of job identifiers that match user-specified 

31889 selection criteria. The list of identifiers returned by the qselect utility conforms to the syntax of 

31890 the batch job identifier list processed by a utility such as qmove, qdel, and qrls. The qselect utility is 

31891 thus a powerful tool for causing another batch system utility to act upon a set of jobs that match 

31892 a list of selection criteria. 

31893 The options of the qselect utility let the user apply a number of useful filters for selecting jobs. 

31894 Each option further restricts the selection of jobs. Many of the selection options allow the 

31895 specification of a relational operator. The FORTRAN-like syntax of the operator—that is, 

31896 " . It. was chosen rather than the C-like " <=" meta-characters. 

31897 The -a option allows users to restrict the selected jobs to those that have been submitted (or 

31898 altered) to wait until a particular time. The time period is determined by the argument of this 

31899 option, which includes both a time and an operator—it is thus possible to select jobs waiting 

31900 until a specific time, jobs waiting until after a certain time, or those waiting for a time before the 

31901 specified time. 

31902 The -A option allows users to restrict the selected jobs to those that have been submitted (or 

31903 altered) to charge a particular account. 

31904 The -c option allows users to restrict the selected jobs to those whose checkpointing interval 

31905 falls within the specified range. 

31906 The -1 option allows users to select those jobs whose resource limits fall within the range 

31907 indicated by the value of the option. For example, a user could select those jobs for which the 

31908 CPU time limit is greater than two hours. 

31909 The -N option allows users to select jobs by job name. For instance, all the parts of a task that 

31910 have been divided in parallel jobs might be given the same name, and thus manipulated as a 

31911 group by means of this option. 

31912 The -q option allows users to select jobs in a specified queue. 

31913 The -r option allows users to select only those jobs with a specified rerun criteria. For instance, a 

31914 user might select only those jobs that can be rerun for use with the qrentn utility. 

31915 The -s option allows users to select only those jobs that are in a certain state. 

31916 The -u option allows users to select jobs that have been submitted to execute under a particular 

31917 account. 

31918 As with other batch utilities, implementors can extend the qselect utility using the -W option. 

31919 The selection criteria provided by the options of the qselect utility allow users to select jobs based 

31920 on all the appropriate attributes that can be assigned to jobs by the qsub utility. When 

31921 implementors extend the qsub utility, or another utilities, using the -W option, they may likewise 
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31922 elect to extend the qselect utility to allow additional selection criteria. 

31923 Historically, the qselect utility has not been a part of existing practice; it is an improvement that 

31924 has been introduced in this volume of IEEE Std. 1003.1-200x. 

31925 FUTURE DIRECTIONS 

31926 None. 

31927 SEE ALSO 

31928 qdel, qrerun, qrls, qselect, qsub, touch, Chapter 3 on page 133 

31929 CHANGE HISTORY 

31930 Derived from IEEE Std. 1003.2d-1994. 
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31931 NAME 

31932 qsig — signal batch jobs 

31933 SYNOPSIS 

31934 BE qsig [—s signal] job_identifier . . . 

31935 


31936 DESCRIPTION 

31937 To signal a batch job is to send a signal to the session leader of the batch job. A batch job is 

31938 signaled by sending a request to the batch server that manages the batch job. The qsig utility is a 

31939 user-accessible batch client that requests the signaling of a batch job. 

31940 The qsig utility shall signal those batch jobs for which a batch job identifier is presented to the 

31941 utility. The qsig utility shall not signal any batch jobs whose batch job identifiers are not 

31942 presented to the utility. 

31943 The qsig utility shall signal batch jobs in the order in which the corresponding batch 

31944 job_identifiers are presented to the utility. If the qsig utility fails to process a batch job_identifier 

31945 successfully, the utility shall proceed to process the remaining batch job_identifiers, if any. 

31946 The qsig utility shall signal batch jobs by sending a Signal Job Request to the batch server that 

31947 manages the batch job. 

31948 For each successfully processed batch job_identifier, the qsig utility shall have received a 

31949 completion reply to each Signal Job Request sent to a batch server at the time the utility exits. 


31950 OPTIONS 

31951 The qsig utility shall conform to the System Interface Definitions volume of 

31952 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

31953 The following option shall be supported by the implementation: 


31954 


-s signal Define the signal to be sent to the batch job. 


31955 

31956 

31957 

31958 


The qsig utility shall accept a signal option-argument that is either a symbolic 
signal name or an unsigned integer signal number (see the POSIX.1-1990 standard. 
Section 3.3.1.1). The qsig utility shall accept signal names for which the SIG prefix 
has been omitted. 


31959 

31960 

31961 

31962 

31963 


If the signal option-argument is a signal name, the qsig utility shall send that name. 

If the signal option-argument is a number, the qsig utility shall send the signal 
value represented by the number. 

If the -s option is not presented to the qsig utility, the utility shall send the signal 
SIGTERM to each signaled batch job. 


31964 OPERANDS 

31965 The qsig utility shall accept one or more operands that conform to the syntax for a batch 

31966 job_identifier (see Section 3.3.1 on page 156). 


31967 STDIN 

31968 Not used. 


31969 INPUT FILES 

31970 None. 
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31971 

31972 

31973 

31974 

31975 

31976 

31977 

31978 

31979 

31980 

31981 

31982 

31983 

31984 

31985 

31986 

31987 

31988 

31989 

31990 

31991 

31992 

31993 

31994 

31995 

31996 

31997 

31998 

31999 

32000 

32001 

32002 

32003 

32004 

32005 

32006 

32007 

32008 

32009 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of qsig: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

Determine the format and contents of date and time strings written by qsig. 
Determine the login name of the user. 

Determine the timezone in which the time and date are written. If the TZ variable 
is not set, an unspecified system default timezone is used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

An implementation of the qsig utility may write informative messages to standard output. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

In addition to the default behavior, the qsig utility shall not be required to write a diagnostic 
message to standard error when the error reply received from a batch server indicates that the 
batch job-identifier does not exist on the server. Whether or not the qsig utility waits to output the 
diagnostic message while attempting to locate the batch job on other servers is implementation- 
dependent. 


LC_TIME 

LOGNAME 

TZ 
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32010 APPLICATION USAGE 

32011 None. 

32012 EXAMPLES 

32013 None. 

32014 RATIONALE 

32015 The qsig utility allows users to signal batch jobs. 

32016 A user may be unable to signal a batch job with the kill utility of the operating system for a 

32017 number of reasons. First, the process ID of the batch job may be unknown to the user. Second, 

32018 the processes of the batch job may be on a remote node. However, by virtue of communication 

32019 between batch nodes, the qsig utility can arrange for the signaling of a process. 

32020 Because a batch job that is not running cannot be signaled, and because the signal may not 

32021 terminate the batch job, the qsig utility is not a substitute for the qdel utility. 

32022 The options of the qsig utility allow the user to specify the signal that is to be sent to the batch 

32023 job. 

32024 The -s option allows users to specify a signal by name or by number, and thus override the 

32025 default signal. The POSIX.1-1990 standard defines signals by both name and number. 

32026 As with other batch utilities, implementors can extend the qsig utility using the -W option. 

32027 The qsig utility is a new utility, vis-a-vis existing practice; it has been defined in this volume of 

32028 IEEE Std. 1003.1-200x in response to user-perceived shortcomings in existing practice. 

32029 FUTURE DIRECTIONS 

32030 None. 

32031 SEE ALSO 

32032 kill, qdel, Chapter 3 on page 133 

32033 CHANGE HISTORY 

32034 Derived from IEEE Std. 1003.2d-1994. 
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32035 NAME 

32036 qstat — show status of batch jobs 

32037 SYNOPSIS 

32038 BE qstat [—f] job_identifier . . . 

32039 qstat —Q [—f] destination . . . 

32040 qstat —B [—f] server_name . . . 

32041 


32042 DESCRIPTION 

32043 The status of a batch job, batch queue, or batch server is obtained by a request to the server. The 

32044 qstat utility is a user-accessible batch client that requests the status of one or more batch jobs, 

32045 batch queues, or servers, and writes the status information to standard output. 

32046 For each successfully processed batch job_identifier , the qstat utility shall display information 

32047 about the corresponding batch job. 

32048 For each successfully processed destination, the qstat utility shall display information about the 

32049 corresponding batch queue. 

32050 For each successfully processed server name, the qstat utility shall display information about the 

32051 corresponding server. 

32052 The qstat utility shall acquire batch job status information by sending a Job Status Request to a 

32053 batch server. The qstat utility shall acquire batch queue status information by sending a Queue 

32054 Status Request to a batch server. The qstat utility shall acquire server status information by 

32055 sending a Server Status Request to a batch server. 


32056 OPTIONS 

32057 The qstat utility shall conform to the System Interface Definitions volume of 

32058 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

32059 The following options shall be supported by the implementation: 


32060 

32061 

32062 

32063 

32064 

32065 

32066 

32067 

32068 


-f 


-Q 


-B 


Specify that a full display is produced. 

The minimum contents of a full display are specified in the STDOUT section. 
Additional contents and format of a full display are implementation-dependent. 
Specify that the operand is a destination. 

The qstat utility shall display information about each batch queue at each 
destination identified as an operand. 

Specify that the operand is a server name. 

The qstat utility shall display information about each server identified as an 
operand. 


32069 OPERANDS 

32070 If the -Q option is presented to the qstat utility, the utility shall accept one or more operands that 

32071 conform to the syntax for a destination (see Section 3.3.2 on page 157). 


32072 If the -B option is presented to the qstat utility, the utility shall accept one or more server_name 

32073 operands. 


32074 If neither the -B nor the -Q option is presented to the qstat utility, the utility shall accept one or 

32075 more operands that conform to the syntax for a batch job_identifier (see Section 3.3.1 on page 

32076 1 56). 
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32077 STDIN 

32078 Not used. 

32079 INPUT FILES 

32080 None. 


32081 ENVIRONMENT VARIABLES 

32082 The following environment variables shall affect the execution of qstat: 

32083 COLUMNS Override the system-selected horizontal screen size. See the System Interface 

32084 Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for 

32085 valid values and results when it is unset or null. 


32086 


HOME Determine the path name of the useds home directory. 


32087 

32088 

32089 

32090 

32091 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


32092 LC_ALL If set to a non-empty string value, override the values of all the other 

32093 internationalization variables. 


32094 

32095 

32096 


LCjCOLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements within regular expressions. 


32097 

32098 

32099 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


32100 LC_MESSAGES 

32101 Determine the locale that should be used to affect the format and contents of 

32102 diagnostic messages written to standard error. 


32103 

32104 

32105 


LCJNUMERIC 

Determine the locale for selecting the radix character used when writing floating¬ 
point formatted output. 


32106 

32107 

32108 

32109 

32110 


LC_TIME Determine the format and contents of date and time strings written by qstat. 

LINES Override the system-selected vertical screen size, used as the number of lines in a 

screenful and the vertical screen size in visual mode. See the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables for 
valid values and results when it is unset or null. 


32111 

32112 

32113 


LOGNAME Determine the login name of the user. 

TERM Determine the terminal type. If this variable is unset or null, and if the -T option is 

not specified, an unspecified default terminal type shall be used. 


32114 TZ Determine the timezone in which the time and date are written. If the TZ variable 

32115 is not set, an unspecified system default timezone is used. 


32116 ASYNCHRONOUS EVENTS 

32117 Default. 
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32119 

32120 

32121 

32122 

32123 

32124 

32125 

32126 

32127 

32128 

32129 

32130 

32131 

32132 

32133 

32134 

32135 

32136 

32137 

32138 

32139 

32140 

32141 

32142 

32143 

32144 

32145 

32146 

32147 

32148 

32149 

32150 

32151 

32152 

32153 

32154 

32155 
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STDOUT 

If an operand presented to the qstat utility is a batch job_identifier and the -f option is not 
specified, the qstat utility shall display the following items on a single line, in the stated order, 
with white space between each item, for each successfully processed operand: 

• The batch job_identifier 

• The batch job name 

• The Job_Owner attribute 

• The CPU time used by the batch job 

• The batch job state 

• The batch job location 

If an operand presented to the qstat utility is a batch job_identifier and the -f option is specified, 
the qstat utility shall display the following items for each success fully processed operand: 

• The batch job-identifier 

• The batch job name 

• The Job_Owner attribute 

• The execution user ID 

• The CPU time used by the batch job 

• The batch job state 

• The batch job location 

• Additional implementation-dependent information, if any, about the batch job or batch 
queue 

If an operand presented to the qstat utility is a destination, the -Q option is specified, and the -f 
option is not specified, the qstat utility shall display the following items on a single line, in the 
stated order, with white space between each item, for each successfully processed operand: 

• The batch queue name 

• The maximum number of batch jobs that are allowed to run in the batch queue concurrently 

• The total number of batch jobs in the batch queue 

• The status of the batch queue 

• For each state, the number of batch jobs in that state in the batch queue and the name of the 
state 

• The type of batch queue (execution or routing) 

If the operands presented to the qstat utility are destinations, the -Q option is specified, and the 
-f option is specified, the qstat utility shall display the following items for each successfully 
processed operand: 

• The batch queue name 

• The maximum number of batch jobs that are allowed to run in the batch queue concurrently 

• The total number of batch jobs in the batch queue 

• The status of the batch queue 
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32156 • For each state, the number of batch jobs in that state in the batch queue and the name of the 

32157 state 

32158 • The type of batch queue (execution or routing) 

32159 • Additional implementation-dependent information, if any, about the batch queue 

32160 If the operands presented to the qstat utility are batch server names, the -B option is specified, 

32161 and the -f option is not specified, the qstat utility shall display the following items on a single 

32162 line, in the stated order, with white space between each item, for each successfully processed 

32163 operand: 

32164 • The batch server name 

32165 • The maximum number of batch jobs that are allowed to run in the batch queue concurrently 

32166 • The total number of batch jobs managed by the batch server 

32167 • The status of the batch server 

32168 • For each state, the number of batch jobs in that state and the name of the state 

32169 If the operands presented to the qstat utility are server names, the -B option is specified, and the 

32170 -f option is specified, the qstat utility shall display the following items for each successfully 

32171 processed operand: 

32172 • The server name 

32173 • The maximum number of batch jobs that are allowed to run in the batch queue concurrently 

32174 • The total number of batch jobs managed by the server 

32175 • The status of the server 

32176 • For each state, the number of batch jobs in that state and the name of the state 

32177 • Additional implementation-dependent information, if any, about the server 

32178 STDERR 

32179 Used only for diagnostic messages. 

32180 OUTPUT FILES 

32181 None. 

32182 EXTENDED DESCRIPTION 

32183 None. 

32184 EXIT STATUS 

32185 The following exit values shall be returned: 

32186 0 Successful completion. 

32187 >0 An error occurred. 

32188 CONSEQUENCES OF ERRORS 

32189 In addition to the default behavior, the qstat utility shall not be required to write a diagnostic 

32190 message to standard error when the error reply received from a batch server indicates that the 

32191 batch job_identifier does not exist on the server. Whether or not the qstat utility waits to output 

32192 the diagnostic message while attempting to locate the batch job on other servers is 

32193 implementation-dependent. 
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32194 APPLICATION USAGE 

32195 None. 

32196 EXAMPLES 

32197 None. 

32198 RATIONALE 

32199 The qstat utility allows users to display the status of jobs and listing the batch jobs in queues. 

32200 The operands of the qstat utility may be either job identifiers, queues (specified as destination 

32201 identifiers), or batch server names. The -Q and -B options, or absence thereof, indicate the 

32202 nature of the operands. 

32203 The other options of the qstat utility allow the user to control the amount of information 

32204 displayed and the format in which it is displayed. Should a user wish to display the status of a 

32205 set of jobs that match a selection criteria, the qselect utility may be used to acquire such a list. 

32206 The -f option allows users to request a "full" display in an implementation-dependent format. 

32207 As with other batch utilities, implementors may extend the qstat utility using the -W option. 

32208 Historically, the qstat utility has been a part of the NQS and its derivatives, the existing practice 

32209 on which it is based. 

32210 FUTURE DIRECTIONS 

32211 None. 

32212 SEE ALSO 

32213 qselect, Chapter 3 on page 133 

32214 CHANGE HISTORY 

32215 Derived from IEEE Std. 1003.2d-1994. 
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32216 NAME 

32217 qsub — submit a script 

32218 SYNOPSIS 

32219 BE 

32220 

32221 

32222 

32223 

32224 

32225 

32226 DESCRIPTION 

32227 To submit a script is to create a batch job that executes the script. A script is submitted by a 

32228 request to a batch server. The qsub utility is a user-accessible batch client that submits a script. 

32229 Upon successful completion, the qsub utility shall have created a batch job that will execute the 

32230 submitted script. 

32231 The qsub utility shall submit a script by sending a Queue Job Request to a batch server. 

32232 The qsub utility shall place the value of the following environment variables in the Variable_List 

32233 attribute of the batch job: HOME, LANG, LOGNAME, PATH, MAIL, SHELL, and TZ. The name 

32234 of the environment variable shall be the current name prefixed with the string PBS_0_. 

32235 Note: If the current value of the HOME variable in the environment space of the qsub utility 

32236 is /aa/bb/cc, then qsub shall place PBS_OJTOME=laalbblcc in the Vciriable_List 

32237 attribute of the batch job. 

32238 In addition to the variables described above, the qsub utility shall add the following variables 

32239 with the indicated values to the variable list: 

32240 PBS_0_WORKDIR The absolute path of the current working directory of the qsub utility process. 

32241 PBS_0_H0ST The name of the host on which the qsub utility is running. 

32242 OPTIONS 

32243 The qsub utility shall conform to the System Interface Definitions volume of 

32244 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

32245 The following options shall be supported by the implementation: 

32246 -a date_tivie Define the time at which a batch job becomes eligible for execution. 

32247 The qsub utility shall accept an option-argument that conforms to the syntax of the 

32248 date_tivie operand of the touch utility. 

32249 Table 4-18 Environment Variable Values (Utilities) 


qsub [—a date_time ] [—A account_string ] [—c interval] 

[—C directive_prefix ][—e path_name] [—h][—j join_list ][—k keep_list] 
[—1 resource_list ][—m mail_options ][—M mail_list ][—N name] 

[—o path_name] [—p priority ][—q destination ][—r y\n] 

[—S path_name_list ][—u user_list ][—v variable_list] [—V] 

[—z] [script] 
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32250 

32251 

32252 

32253 

32254 

32255 

32256 

32257 

32258 

32259 

32260 

32261 

32262 

32263 

32264 

32265 

32266 

32267 

32268 

32269 

32270 

32271 

32272 

32273 

32274 

32275 

32276 

32277 

32278 

32279 

32280 

32281 

32282 

32283 

32284 

32285 

32286 

32287 

32288 

32289 

32290 

32291 

32292 
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Variable Name 

Value at qsub Time 

PB S_0_H OME 

PBS_0_HOST 

PBS_0_LANG 

PBS_0_LOGNAME 

PBS_0_PATH 

PBS_0_MAIL 

PBS_0_SHELL 

PBSJDJTZ 

PBS_0_WORKDIR 

HOME 

Client host name 

LANG 

LOGNAME 

PATH 

MAIL 

SHELL 

TZ 

Current working directory 


Note: The server that initiates execution of the batch job will add other I 

variables to the batch job's environment; see Section 3.2.2.1 on page I 
139. I 

The qsub utility shall set the ExecutionJTime attribute of the batch job to the number I 
of seconds since the Epoch that is equivalent to the local time expressed by the I 
value of the date_time option-argument. The Epoch is defined in the System I 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.151, Epoch. I 

If the -a option is not presented to the qsub utility, the utility shall set the I 
ExecutionJTime attribute of the batch job to a time (number of seconds since the I 
Epoch) that is earlier than the time at which the utility exits. I 

-A account_string I 

Define the account to which the resource consumption of the batch job should be I 
charged. I 

The syntax of the account_string option-argument is unspecified. I 

The qsub utility shall set the Account_Name attribute of the batch job to the value of I 
the account_string option-argument. I 

If the -A option is not presented to the qsub utility, the utility shall omit the I 
Account_Name attribute from the attributes of the batch job. I 

-c interval Define whether the batch job should be checkpointed, and if so, how often. I 

The qsub utility shall accept a value for the interval option-argument that is one of I 
the following: I 

n No checkpointing shall be performed on the batch batch job I 

(NCLCHECKPOINT). I 

s Checkpointing shall be performed only when the batch server is shut I 

down (CHECKPOINT.AT_SHUTDOWN). I 

c Automatic periodic checkpointing shall be performed at the I 

Minimum_Cipu_Interval attribute of the batch queue, in units of CPU I 
minutes (CHECKPOINT.AT_MIN_CPU_INTERVAL). I 

c-minutes Automatic periodic checkpointing shall be performed every minutes I 
of CPU time, or every Minimum_Cpu_Interval minutes, whichever is I 
greater. The minutes argument shall conform to the syntax for I 
unsigned integers and shall be greater than zero. I 

The qsub utility shall set the Checkpoint attribute of the batch job to the value of the I 
interval option-argument. I 
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32295 

32296 

32297 

32298 

32299 

32300 

32301 

32302 

32303 

32304 

32305 

32306 

32307 

32308 

32309 

32310 

32311 

32312 

32313 

32314 

32315 

32316 

32317 

32318 

32319 

32320 

32321 

32322 

32323 

32324 

32325 

32326 

32327 

32328 

32329 

32330 

32331 

32332 

32333 

32334 

32335 

32336 

32337 

32338 


If the -c option is not presented to the qsub utility, the utility shall set the 
Checkpoint attribute of the batch job to the single character 'u' 
(CHECKPOINT_UNSPECIFIED). 

-C directivejprefix 

Define the prefix that declares a directive to the qsub utility within the script. 

The directivejprefix is not a batch job attribute; it affects the behavior of the qsub 

utility. 

If the -C option is presented to the qsub utility, and the value of the directivejprefix 
option-argument is the null string, the utility shall not scan the script file for 
directives. If the -C option is not presented to the qsub utility, then the value of the 
PBS_DPREFIX environment variable is used. If the environment variable is not 
defined, then #PBS encoded in the portable character set is the default. 

-e pathjiame Define the path to be used for the standard error stream of the batch job. 

The qsub utility shall accept a path_name option-argument that conforms to the 
syntax of the pathjiame element defined in the POSIX.1-1990 standard, which can 
be preceded by a host name element of the form hostname :. 

If the pathjiame option-argument constitutes an absolute path name, the qsub 
utility shall set the Error_Path attribute of the batch job to the value of the 
pathjiame option-argument. 

If the pathjiame option-argument constitutes a relative path name and no host 
name element is specified, the qsub utility shall set the Error_Path attribute of the 
batch job to the value of the absolute path name derived by expanding the 
pathjiame option-argument relative to the current directory of the process 
executing qsub. 

If the pathjiame option-argument constitutes a relative path name and a host name 
element is specified, the qsub utility shall set the Error_Path attribute of the batch 
job to the value of the pathjiame option-argument without expansion. The host 
name element shall be included. 

If the pathjiame option-argument does not include a host name element, the qsub 
utility shall prefix the path name with hostname :, where hostname is the name of the 
host upon which the qsub utility is being executed. 

If the -e option is not presented to the qsub utility, the utility shall set the 
Error_Path attribute of the batch job to the host name and path of the current 
directory of the submitting process and the default file name. 

The default file name for standard error has the following format: 

job_name.esequence_number 

-h Specify that a USER hold is applied to the batch job. 

The qsub utility shall set the value of the Hold_Types attribute of the batch job to the 
value USER. 

If the -h option is not presented to the qsub utility, the utility shall set the 
Hold_Types attribute of the batch job to the value NO_HOLD. 

-j join_list Define which streams of the batch job are to be merged. The qsub -j option shall 
accept a value for the joinjist option-argument that is a string of alphanumeric 
characters in the portable character set (see the System Interface Definitions 
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32339 

32340 

32341 

32342 

32343 

32344 

32345 

32346 

32347 

32348 

32349 

32350 

32351 

32352 

32353 

32354 

32355 

32356 

32357 

32358 

32359 

32360 

32361 

32362 

32363 

32364 

32365 

32366 

32367 

32368 

32369 

32370 

32371 

32372 

32373 

32374 

32375 

32376 

32377 

32378 

32379 

32380 


volume of IEEE Std. 1003.1-200x, Section 6.1, Portable Character Set). 

The qsnb utility shall accept a joinjist option-argument that consists of one or 
more of the characters ' e' and ' o' or the single character ' n'. 

All of the other batch job output streams specified will be merged into the output 
stream represented by the character listed first in the joinjist option-argument. 

For each unique character in the joinjist option-argument, the qsub utility shall 
add a value to the Join_Path attribute of the batch job as follows, each representing 
a different batch job stream to join: 

e The standard error of the batch batch job (JOIN_STD_ERROR). 
o The standard output of the batch batch job (JOIN_STD_OUTPUT). 

An existing Join_Path attribute can be cleared by the following join type: 
n NO JOIN 

If n is specified, then no files are joined. The qsub utility shall consider it an error if 
any join type other than n is combined with join type n. 

Strictly conforming applications shall not repeat any of the characters ' e', ' o', or 
' n' within the joinjist option-argument. The qsub utility shall permit the 
repetition of characters, but shall not assign additional meaning to the repeated 
characters. 

An implementation may define other join types. The conformance document for an 
implementation shall describe any additional batch job streams, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. 

If the -j option is not presented to the qsub utility, the utility shall set the value of 
the }oin_Path attribute of the batch job to NO JOIN. 

-k keepjist Define which output of the batch job to retain on the execution host. 

The qsub -k option shall accept a value for the keepjist option-argument that is a 
string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set). 

The qsub utility shall accept a keepjist option-argument that consists of one or 
more of the characters ' e' and ' o' or the single character ' n'. 

For each unique character in the keepjist option-argument, the qsub utility shall 
add a value to the Keep_Files attribute of the batch job as follows, each representing 
a different batch job stream to keep: 

e The standard error of the batch batch job (KEEP_STD_ERROR). 

o The standard output of the batch batch job (KEEP_STD_OUTPUT). 

If both e and o are specified, then both files are retained. An existing Keep_Files 
attribute can be cleared by the following keep type: 

n NOJCEEP 

If n is specified, then no files are retained. The qsnb utility shall consider it an error 
if any keep type other than n is combined with keep type n. 

Strictly conforming applications shall not repeat any of the characters ' e', ' o', or 
' n' within the keepjist option-argument. The qsnb utility shall permit the 
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32393 

32394 
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repetition of characters, but shall not assign additional meaning to the repeated 
characters. 

An implementation may define other keep types. The conformance document for 
an implementation shall describe any additional keep types, how they are 
specified, their internal behavior, and how they affect the behavior of the utility. If 
the -k option is not presented to the qsub utility, the utility shall set the Keep_Files 
attribute of the batch job to the value NO_KEEP. 

-1 resourceJist 

Define the resources that are allowed or required by the batch job. 

The qsub utility shall accept a resource Jist option-argument that conforms to the 
following syntax: 

resource=value [, , resource=value ,, ...] 

For each resource listed in the resource Jist option-argument, the qsub utility shall 
add one entry in the Resource_List attribute of the batch job, each such entry 
containing the name of the resource and the value. 

If the -1 option is not presented to the qsub utility, the utility shall omit the 
ResourceJ^ist attribute from the attributes of the batch job. See Section 3.3.3 on page 
157 for a means of removing keyword-value (and value@keyzvord) pairs, and other 
general rules for list-oriented batch job attributes. 

Note: See <REFERENCE UNDEFINED>(???)Table for a list of the reserved 

resource names. 


-m mail_options 

Define the points in the execution of the batch job at which the batch server that 
manages the batch job shall send mail about a change in the state of the batch job. 

The qsub -m option shall accept a value for the mailjoptions option-argument that 
is a string of alphanumeric characters in the portable character set (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set). 

The qsub utility shall accept a value for the viailjoptions option-argument that is a 
string of one or more of the characters ' e', ' b', and ' a', or the single character 
' n'. 

For each unique character in the mailjoptions option-argument, the qsub utility shall 
add a value to the Mailjlsers attribute of the batch job as follows, each 
representing a different time during the life of a batch job at which to send mail: 

e MAIL_AT_EXIT 

b MAIL_AT_BEGINNING 

a MAIL_AT_ABORT 

If any of these characters are duplicated in the mailjoptions option-argument, the 
duplicates shall be ignored. 

An existing Mail_Points attribute can be cleared by the following mail type: 
n NO_MAIL 

If n is specified, then mail is not sent. The qsub utility shall consider it an error if 
any mail type other than n is combined with mail type n. 
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Strictly conforming applications shall not repeat any of the characters ' e', ' b', 
' a', or ' n' within the mailjjptions option-argument. 

The qsub utility shall permit the repetition of characters, but shall not assign 
additional meaning to the repeated characters. An implementation may define 
other mail types. The conformance document for an implementation shall describe 
any additional mail types, how they are specified, their internal behavior, and how 
they affect the behavior of the utility. 

If the -m option is not presented to the qsub utility, the utility shall set the 
Mail_Points attribute to the value MAIL_AT_ABORT. 

-M mailjiist Define the list of users to which a batch server that executes the batch job shall 
send mail, if the server sends mail about the batch job. 

The syntax of the mail_list option-argument is unspecified. 

If the implementation of the qsub utility uses a name service to locate users, the 
utility should accept the syntax used by the name service. 

If the implementation of the qsub utility does not use a name service to locate 
users, the implementation should accept the following syntax for user names: 

mail_address [, , mail_address ,, ...] 

The interpretation of mail_address is implementation-dependent. 

The qsub utility shall set the Mail_Users attribute of the batch job to the value of the 
mailjist option-argument. 

If the -M option is not presented to the qsub utility, the utility shall place only the 
user name and host name for the current process in the MailJUsers attribute of the 
batch job. 

-N name Define the name of the batch job. 

The qsub -N option shall accept a value for the name option-argument that is a 
string of up to 15 alphanumeric characters in the portable character set (see the 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 6.1, Portable 
Character Set) where the first character is alphabetic. 

The qsub utility shall set the value of the Job_Name attribute of the batch job to the 
value of the name option-argument. 

If the -N option is not presented to the qsub utility, the utility shall set the 
Job_Name attribute of the batch job to the name of the script argument from which 
the directory specification if any, has been removed. 

If the -N option is not presented to the qsub utility, and the script is read from 
standard input, the utility shall set the Job_Name attribute of the batch job to the 
value STDIN. 

-o path_name Define the path for the standard output of the batch job. 

The qsub utility shall accept a path_name option-argument that conforms to the 
syntax of the path_name element defined in the POSIX.1-1990 standard, which can 
be preceded by a host name element of the form hostname :. 

If the path_name option-argument constitutes an absolute path name, the qsub 
utility shall set the Output_Path attribute of the batch job to the value of the 
path_name option-argument without expansion. 
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If the pathjname option-argument constitutes a relative path name and no host 
name element is specified, the qsub utility shall set the Output_Path attribute of the 
batch job to the path name derived by expanding the value of the path_name 
option-argument relative to the current directory of the process executing the qsub. 

If the path_name option-argument constitutes a relative path name and a host name 
element is specified, the qsub utility shall set the Output _Puth attribute of the batch 
job to the value of the path_name option-argument without expansion. 

If the path_name option-argument does not specify a host name element, the qsub 
utility shall prefix the path name with hostname :, where hostname is the name of the 
host upon which the qsub utility is executing. 

If the -o option is not presented to the qsub utility, the utility shall set the 
Output_Path attribute of the batch job to the host name and path of the current 
directory of the submitting process and the default file name. 

The default file name for standard output has the following format: 

job_name.osequence_number 

-p priority Define the priority the batch job should have relative to other batch jobs owned by 
the batch server. 

The qsub utility shall set the Priority attribute of the batch job to the value of the 
priority option-argument. 

If the -p option is not presented to the qsub utility, the value of the Priority 
attribute is implementation-dependent. 

The qsub utility shall accept a value for the priority option-argument that conforms 
to the syntax for signed decimal integers, and which is not less than -1024 and not 
greater than 1 023. 

-q destination 

Define the destination of the batch job. 

The destination is not a batch job attribute; it determines the batch server, and 
possibly the batch queue, to which the qsub utility batch queues the batch job. 

The qsub utility shall submit the script to the batch server named by the destination 
option-argument or the server that owns the batch queue named in the destination 
option-argument. 

The qsub utility shall accept an option-argument for the -q option that conforms to 
the syntax for a destination (see Section 3.3.2 on page 157). 

If the -q option is not presented to the qsub utility, the qsub utility shall submit the 
batch job to the default destination. The mechanism for determining the default 
destination is implementation-dependent. 

-ry\n Define whether the batch job is rerunable. 

If the value of the option-argument is yy , the qsub utility shall set the Rerunable 
attribute of the batch job to TRUE. 

If the value of the option-argument is nn, the qsub utility shall set the Rerunable 
attribute of the batch job to FALSE. 

If the -r option is not presented to the qsub utility, the utility shall set the Rerunable 
attribute of the batch job to TRUE. 
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-S path_name_list 

Define the path name to the shell under which the batch job is to execute. 

The qsub utility shall accept a path_namejist option-argument that conforms to the 
following syntax: 

pathname [@host][,, pathname [@host],, ...] 

The qsub utility shall allow only one path name for a given host name. The qsub 
utility shall allow only one path name that is missing a corresponding host name. 

The qsub utility shall add a value to the Shell_Path_List attribute of the batch job for 
each entry in the path_name_list option-argument. 

If the -S option is not presented to the qsub utility, the utility shall set the 
Shell_Pnth_List attribute of the batch job to the null string. 

The conformance document for an implementation shall describe the mechanism 
used to set the default shell and determine the current value of the default shell. 
An implementation shall provide a means for the installation to set the default 
shell to the login shell of the user under which the batch job is to execute. See 
Section 3.3.3 on page 157 for a means of removing keyword =value (and 
value@keyzvord) pairs and other general rules for list-oriented batch job attributes. 

-u user_list Define the user name under which the batch job is to execute. 

The qsub utility shall accept a user_list option-argument that conforms to the 
following syntax: 

username [ Qhost ][,, username [ Qhost ],, ...] 

The qsub utility shall accept only one user name that is missing a corresponding 
host name. The qsub utility shall accept only one user name per named host. 

The qsub utility shall add a value to the User_List attribute of the batch job for each 
entry in the user_list option-argument. 

If the -u option is not presented to the qsub utility, the utility shall set the User_List 
attribute of the batch job to the user name from which the utility is executing. See 
Section 3.3.3 on page 157 for a means of removing keyword=volue (and 
value@keyzvord) pairs and other general rules for list-oriented batch job attributes. 

-v variablejist 

Add to the list of variables that are exported to the session leader of the batch job. 

A variablejist is a set of strings of either the form <variable> or <variable-value>, 
delimited by commas. 

If the -v option is presented to the qsub utility, the utility shall also add, to the 
environment Variable_List attribute of the batch job, every variable named in the 
environment variablejist option-argument and, optionally, values of specified 
variables. 

If a value is not provided on the command line, the qsub utility shall set the value 
of each variable in the environment Variable_List attribute of the batch job to the 
value of the corresponding environment variable for the process in which the 
utility is executing; see Table 4-18 on page 840. 

A conforming application shall not repeat a variable in the environment 
variablejist option-argument. 
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32553 The qsub utility shall not repeat a variable in the environment Variable_List 

32554 attribute of the batch job. See Section 3.3.3 on page 157 for a means of removing 

32555 keyword =value (and value@keyzvord) pairs and other general rules for list-oriented 

32556 batch job attributes. 

32557 -V Specify that all of the environment variables of the process are exported to the 

32558 context of the batch job. 

32559 The qsub utility shall place every environment variable in the process in which the 

32560 utility is executing in the list and shall set the value of each variable in the attribute 

32561 to the value of that variable in the process. 

32562 -z Specify that the utility does not write the batch job_identifier of the created batch 

32563 job to standard output. 

32564 If the -z option is presented to the qsub utility, the utility shall not write the batch 

32565 job_identifier of the created batch job to standard output. 

32566 If the -z option is not presented to the qsub utility, the utility shall write the 

32567 identifier of the created batch job to standard output. 

32568 OPERANDS 

32569 The qsub utility shall accept a script operand that indicates the path to the script of the batch job. 

32570 If the script operand is not presented to the qsub utility, or if the operand is the single-character 

32571 string ' -', the utility shall read the script from standard input. 

32572 If the script represents a partial path, the qsub utility shall expand the path relative to the current 

32573 directory of the process executing the utility. 


32574 STDIN 


The qsub utility reads the script of the batch job from standard input if the script operand is 
omitted or is the single character ' -'. 


32577 INPUT FILES 

32578 In addition to binding the file indicated by the script operand to the batch job, the qsub utility 

32579 reads the script file and acts on directives in the script. 

32580 ENVIRONMENT VARIABLES 

32581 The following environment variables shall affect the execution of qsub : 

32582 LANG Provide a default value for the internationalization variables that are unset or null. 

32583 If LANG is unset or null, the corresponding value from the implementation- 

32584 dependent default locale shall be used. If any of the internationalization variables 

32585 contains an invalid setting, the utility shall behave as if none of the variables had 

32586 been defined. 

32587 LC_ALL If set to a non-empty string value, override the values of all the other 

32588 internationalization variables. 

32589 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

32590 characters (for example, single-byte as opposed to multi-byte characters in 

32591 arguments). 

32592 LC_MESSAGES 

32593 Determine the locale that should be used to affect the format and contents of 

32594 diagnostic messages written to standard error. 

32595 LC_TIME Determine the format and contents of date and time strings written by qsub. 
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32596 

32597 

32598 

32599 

32600 

32601 

32602 

32603 ASYNCHRONOUS EVENTS 

32604 Once created, a batch job exists until it exits, aborts, or is deleted. 

32605 After a batch job is created by the qsub utility, batch servers might route, execute, modify, or 

32606 delete the batch job. 

32607 STDOUT 

32608 The qsub utility writes the batch job_identifier assigned to the batch job to standard output, unless 

32609 the -z option is specified. 

32610 STDERR 

32611 Used only for diagnostic messages. 

32612 OUTPUT FILES 

32613 None. 

32614 EXTENDED DESCRIPTION 

32615 Script Preservation 

32616 The qsub utility shall make the script available to the server executing the batch job in such a way 

32617 that the server executes the script as it exists at the time of submission. 

32618 The qsub utility can send a copy of the script to the server with the Queue Job Request or store a 

32619 temporary copy of the script in a location specified to the server. 

32620 Option Specification 

32621 A script can contain directives to the qsub utility. 

32622 The qsub utility shall scan the lines of the script for directives, skipping blank lines, until the first 

32623 line that begins with a string other than the directive string; if directives occur on subsequent 

32624 lines, the utility shall ignore those directives. 

32625 Lines are separated by a <newline>. If the first line of the script begins with " # !" or a colon 

32626 (' :'), then it is skipped. The qsub utility shall process a line in the script as a directive if, and 

32627 only if, the string of characters from the first non-white-space character on the line until the first 

32628 <space> or <tab> character on the line match the directive prefix. If a line in the script contains a 

32629 directive and the final characters of the line are backslash (' ) ' and <newline>, then the next 

32630 line shall be interpreted as a continuation of that directive. 

32631 The qsub utility shall process the options and option-arguments contained on the directive prefix 

32632 line using the same syntax as if the options were input on the qsub utility. 

32633 The qsub utility shall continue to process a directive prefix line until after a <newline> is 

32634 encountered. An implementation may also ignore comments of the shell that will interpret the 

32635 script. An implementation shall describe in the conformance document the format of any shell 

32636 comments that it will recognize. 


LOGNAME Determine the login name of the user. 

PBSJDPREFIX 

Determine the default prefix for directives within the script. 

SHELL Determine the path name of the preferred command language interpreter of the 
user. 

TZ Determine the timezone in which the time and date are written. If the TZ variable 

is not set, an unspecified system default timezone is used. 
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If an option is present in both a directive and the arguments to the qsub utility, the utility shall 
ignore the option and the corresponding option-argument, if any, in the directive. 

If an option that is present in the directive is not present in the arguments to the qsub utility, the 
utility shall process the option and the option-argument, if any. 

In order of preference, the qsub utility shall select the directive prefix from one of the following 
sources: 

• If the -C option is presented to the utility, the value of the directive_prefix option-argument 

• If the environment variable PBS_DPREFIX is defined, the value of that variable 

• The four-character string " #PBS " encoded in the portable character set 
If the -C option is present in the script file it shall be ignored. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

The qsub utility allows users to create a batch job that will process the script specified as the 
operand of the utility. 

The options of the qsub utility allow users to control many aspects of the queuing and execution 
of a batch job. 

The -a option allows users to designate the time after which the batch job will become eligible to 
run. By specifying an execution time, users can take advantage of resources at off-peak hours, 
synchronize jobs with chronologically predictable events, and perhaps take advantage of off- 
peak pricing of computing time. For these reasons and others, a timing option is existing practice 
on the part of almost every batch system, including NQS. 

The -A option allows users to specify the account that will be charged for the batch job. Support 
for account is not mandatory for conforming batch servers. 

The -C option allows users to prescribe the prefix for directives within the script file. The default 
prefix " #PBS " may be inappropriate if the script will be interpreted with an alternate shell, as 
specified by the -S option. 

The -c option allows users to establish the checkpointing interval for their jobs. A checkpointing 
system, which is not defined by this volume of IEEE Std. 1003.1-200x, allows recovery of a batch 
job at the most recent checkpoint in the event of a crash. Checkpointing is typically used for jobs 
that consume expensive computing time or must meet a critical schedule. Users should be 
allowed to make the tradeoff between the overhead of checkpointing and the risk to the timely 
completion of the batch job; therefore, this volume of IEEE Std. 1003.1-200x provides the 
checkpointing interval option. Support for checkpointing is optional for batch servers. 
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The -e option allows users to redirect the standard error streams of their jobs to a non-default 
path. For example, if the submitted script generally produces a great deal of useless error output, 
a user might redirect the standard error output to the null device. Or, if the file system holding 
the default location (the home directory of the user) has too little free space, the user might 
redirect the standard error stream to a file in another file system. 

The -h option allows users to create a batch job that is held until explicitly released. The ability 
to create a held job is useful when some external event must complete before the batch job can 
execute. For example, the user might submit a held job and release it when the system load has 
dropped. 

The -j option allows users to merge the standard error of a batch job into its standard output 
stream, which has the advantage of showing the sequential relationship between output and 
error messages. 

The -1 option allows users to limit the resources that will be consumed by the batch job. For 
example, the user may wish to limit the amount of CPU time that can be consumed by a batch 
job that has a risk of entering an infinite loop. 

The -m option allows users to designate those points in the execution of a batch job at which 
mail will be sent to the submitting user, or to the account(s) indicated by the -M option. By 
requesting mail notification at points of interest in the life of a job, the submitting user, or other 
designated users, can track the progress of a batch job. 

The -N option allows users to associate a name with the batch job. The job name in no way 
affects the processing of the batch job, but rather serves as a mnemonic handle for users. For 
example, the batch job name can help the user distinguish between multiple jobs listed by the 
qstat utility. 

The -o option allows users to redirect the standard output stream. A user might, for example, 
wish to redirect to the null device the standard output stream of a job that produces copious yet 
superfluous output. 

The -P option allows users to designate the relative priority of a batch job for selection from a 
queue. 

The -q option allows users to specify an initial queue for the batch job. If the user specifies a 
routing queue, the batch batch server routes the batch job to another queue for execution or 
further routing. If the user specifies a non-routing queue, the batch server of the queue 
eventually executes the batch job. 

The -r option allows users to control whether the submitted job will be rerun if the controlling 
batch node fails during execution of the batch job. The -r option likewise allows users to 
indicate whether or not the batch job is eligible to be rerun by the qrerun utility. Some jobs cannot 
be correctly rerun because of changes they make in the state of databases or other aspects of 
their environment. This volume of IEEE Std. 1003.1-200x specifies that the default, if the -r 
option is not presented to the utility, will be that the batch job cannot be rerun, since the result of 
rerunning a non-rerunable job might be catastrophic. 

The -S option allows users to specify the program (usually a shell) that will be invoked to 
process the script of the batch job. This option has been modified to allow a list of shell names 
and locations associated with different hosts. 

The -u option is useful when the submitting user is authorized to use more than one account on 
a given host, in which case the -u option allows the user to select from among those accounts. 
The option-argument is a list of user-host pairs, so that the submitting user can provide different 
user identifiers for different nodes in the event the batch job is routed. The -u option provides a 
lot of flexibility to accommodate sites with complex account structures. Users that have the 
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32726 same user identifier on all the hosts they are authorized to use will not need to use the -u option. I 

32727 The -V option allows users to export all their current environment variables, as of the time the I 

32728 batch job is submitted, to the context of the processes of the batch job. I 

32729 The -v option allows users to export specific environment variables from their current process I 

32730 to the processes of the batch job. I 

32731 The -z option allows users to suppress the writing of the batch job identifier to standard output. I 

32732 The -z option is an existing NQS practice that has been standardized. I 

32733 As with other batch utilities, implementors can extend the qsub utility using the -W option. I 

32734 Historically, the qsub utility has served the batch job-submission function in the NQS system, the I 

32735 existing practice on which it is based. Some changes and additions have been made to the qsub I 

32736 utility in this volume of IEEE Std. 1003.1-200x, vis-a-vis NQS, as a result of the growing pool of I 

32737 experience with distributed batch systems. I 

32738 The set of features of the qsub utility as defined in this volume of IEEE Std. 1003.1-200x appears I 

32739 to incorporate all the common existing practice on potentially POSIX-conformant platforms. I 

32740 Where implementors wish to extend the functionality of their qsub utility, they may (as defined I 

32741 by the base standard) use the -W option to provide implementation-dependent extensions. I 

32742 FUTURE DIRECTIONS I 

32743 None. I 

32744 SEE ALSO I 

32745 qrerun, qstat, touch, Chapter 3 on page 133 I 

32746 CHANGE HISTORY I 

32747 Derived from IEEE Std. 1003.2d-1994. I 
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32748 NAME 

32749 read — read a line from standard input 

32750 SYNOPSIS 

32751 read [— r] var. . . 

32752 DESCRIPTION 

32753 The read utility shall read a single line from standard input. 

32754 By default, unless the -r option is specified, backslash (' \ ') shall act as an escape character, as 

32755 described in Section 2.2.1 on page 36. If standard input is a terminal device and the invoking 

32756 shell is interactive, read shall prompt for a continuation line when: 

32757 • The shell reads an input line ending with a backslash, unless the -r option is specified. 

32758 • A here-document is not terminated after a <newline> character is entered. 

32759 The line shall be split into fields as in the shell (see Section 2.6.5 on page 58); the first field shall 

32760 be assigned to the first variable var, the second field to the second variable var, and so on. If 

32761 there are fewer var operands specified than there are fields, the leftover fields and their 

32762 intervening separators shall be assigned to the last var. If there are fewer fields than var s, the 

32763 remaining var s shall be set to empty strings. 

32764 The setting of variables specified by the var operands shall affect the current shell execution 

32765 environment; see Section 2.12 on page 90. If it is called in a subshell or separate utility execution 

32766 environment, such as one of the following: 

32767 (read foo) 

32768 nohup read . . . 

32769 find . —exec read ... \; 

32770 it shall not affect the shell variables in the caller's environment. 

32771 OPTIONS 

32772 The read utility shall conform to the System Interface Definitions volume of I 

32773 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

32774 The following option is supported: 

32775 -r Do not treat a backslash character in any special way. Consider each backslash to 

32776 be part of the input line. 

32777 OPERANDS 

32778 The following operand shall be supported: 

32779 var The name of an existing or nonexisting shell variable. 

32780 STDIN 

32781 The standard input shall be a text file. I 

32782 INPUT FILES 

32783 None. 


32784 ENVIRONMENT VARIABLES 

32785 The following environment variables shall affect the execution of read : 


32786 IFS Determine the internal field separators used to delimit fields; see Section 2.5.3 on 

32787 page 45. 


32788 

32789 

32790 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
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32791 contains an invalid setting, the utility shall behave as if none of the variables had 

32792 been defined. 

32793 LC_ALL If set to a non-empty string value, override the values of all the other 

32794 internationalization variables. 

32795 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

32796 characters (for example, single-byte as opposed to multi-byte characters in 

32797 arguments). 

32798 LC_MESSAGES 

32799 Determine the locale that should be used to affect the format and contents of 

32800 diagnostic messages written to standard error. 

32801 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

32802 PS2 Provide the prompt string that an interactive shell shall write to standard error 

32803 when a line ending with a backslash is read and the -r option was not specified, or 

32804 if a here-document is not terminated after a <newline> character is entered. 

32805 ASYNCHRONOUS EVENTS 

32806 Default. 

32807 STDOUT 

32808 Not used. 

32809 STDERR 

32810 Used for diagnostic messages and prompts for continued input. 

32811 OUTPUT FILES 

32812 None. 

32813 EXTENDED DESCRIPTION 

32814 None. 

32815 EXIT STATUS 

32816 The following exit values shall be returned: 

32817 0 Successful completion. 

32818 >0 End-of-file was detected or an error occurred. 

32819 CONSEQUENCES OF ERRORS 

32820 Default. 

32821 APPLICATION USAGE 

32822 The read utility has historically been a shell built-in. 

32823 The -r option is included to enable read to subsume the purpose of the line utility, which is not I 

32824 included in IEEE Std. 1003.1-200x. I 

32825 The results are undefined if an end-of-file is detected following a backslash at the end of a line 

32826 when -r is not specified. 

32827 EXAMPLES 

32828 The following command: 

32829 while read —r xx yy 

32830 do 

32831 printf "%s %s\n" "$yy" "$xx" 

32832 done < input_file 
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32833 prints a file with the first field of each line moved to the end of the line. 

32834 RATIONALE 

32835 The read utility historically has been a shell built-in. It was separated off into its own utility to 

32836 take advantage of the richer description of functionality introduced by this volume of 

32837 IEEE Std. 1003.1-200x. 

32838 Since read affects the current shell execution environment, it is generally provided as a shell 

32839 regular built-in. If it is called in a subshell or separate utility execution environment, such as one 

32840 of the following: 

32841 (read foo) 

32842 nohup read . . . 

32843 find . —exec read ... \; 

32844 it does not affect the shell variables in the environment of the caller. 

32845 FUTURE DIRECTIONS 

32846 None. 

32847 SEE ALSO 

32848 None. 

32849 CHANGE HISTORY 

32850 First released in Issue 2. 

32851 Issue 4 

32852 Relocated from the sh description for alignment with the ISO/IEC 9945-2:1993 standard. 
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32853 NAME 

32854 renice — set nice values of running processes 

32855 SYNOPSIS 

32856 UP renice — n increment [—g | — p | — u] ID . . . 

32857 


32858 DESCRIPTION 

32859 The renice utility shall request that the nice values (see the System Interface Definitions volume I 

32860 of IEEE Std. 1003.1-200x, Section 3.245, Nice Value) of one or more running processes be I 

32861 changed. By default, the applicable processes are specified by their process IDs. When a process 

32862 group is specified (see -g), the request applies to all processes in the process group. 

32863 The nice value shall be bounded in an implementation-dependent manner. If the requested 

32864 increment would raise or lower the nice value of the executed utility beyond implementation- 

32865 dependent limits, then the limit whose value was exceeded shall be used. 

32866 When a user is renice d, the request applies to all processes whose saved set-user-ID matches the 

32867 user ID corresponding to the user. 

32868 Regardless of which options are supplied or any other factor, renice shall not alter the nice values 

32869 of any process unless the user requesting such a change has appropriate privileges to do so for 

32870 the specified process. If the user lacks appropriate privileges to perform the requested action, the 

32871 utility shall return an error status. 

32872 The saved set-user-ID of the user's process shall be checked instead of its effective user ID when 

32873 renice attempts to determine the user ID of the process in order to determine whether the user 

32874 has appropriate privileges. 


32875 OPTIONS 

32876 The renice utility shall conform to the System Interface Definitions volume of I 

32877 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

32878 The following options shall be supported: 

32879 -g Interpret all operands as unsigned decimal integer process group IDs. 


32880 

32881 

32882 

32883 

32884 

32885 

32886 


-n increment Specify how the nice value of the specified process or processes is to be adjusted. 

The increment option-argument is a positive or negative decimal integer that shall 
be used to modify the nice value of the specified process or processes. 

Positive increment values shall cause a lower nice value. Negative increment values 
may require appropriate privileges and shall cause a higher nice value. 

-p Interpret all operands as unsigned decimal integer process IDs. The -p option is 

the default if no options are specified. 


32887 -U 

32888 

32889 

32890 


Interpret all operands as users. If a user exists with a user name equal to the 
operand, then the user ID of that user is used in further processing. Otherwise, if 
the operand represents an unsigned decimal integer, it shall be used as the numeric 
user ID of the user. 


32891 OPERANDS 

32892 The following operands shall be supported: 

32893 ID A process ID, process group ID, or user name /user ID, depending on the option 

32894 selected. 
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32895 STDIN 

32896 Not used. 

32897 INPUT FILES 

32898 None. 


32899 ENVIRONMENT VARIABLES 

32900 The following environment variables shall affect the execution of renice : 


32901 

32902 

32903 

32904 

32905 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


32906 

32907 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


32908 

32909 

32910 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


32911 LC_MESSAGES 

32912 Determine the locale that should be used to affect the format and contents of 

32913 diagnostic messages written to standard error. 

32914 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


32915 ASYNCHRONOUS EVENTS 

32916 Default. 


32917 STDOUT 

32918 Not used. 


32919 STDERR 

32920 Used only for diagnostic messages. 

32921 OUTPUT FILES 

32922 None. 


32923 EXTENDED DESCRIPTION 

32924 None. 


32925 EXIT STATUS 

32926 The following exit values shall be returned: 

32927 0 Successful completion. 

32928 >0 An error occurred. 


32929 CONSEQUENCES OF ERRORS 

32930 Default. 
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32931 APPLICATION USAGE 

32932 Application writers should note that this utility need not be provided on systems that do not 

32933 support the User Portability Utilities option. 

32934 EXAMPLES 


32935 

32936 

32937 

32938 

32939 

32940 

32941 


1. Adjust the nice value so that process IDs 987 and 32 would have a lower nice value: 

renice —n 5 —p 987 32 

2. Adjust the nice value so that group IDs 324 and 76 would have a higher nice value, if the 
user has the appropriate privileges to do so: 

renice —n —4 —g 324 76 

3. Adjust the nice value so that numeric user ID 8 and user sas would have a lower nice 
value: 


32942 renice — n 4 —u 8 sas 

32943 Useful nice value increments on historical systems include 19 or 20 (the affected processes run 

32944 only when nothing else in the system attempts to run) and any negative number (to make 

32945 processes run faster). 

32946 RATIONALE 

32947 The gid, pid, and user specifications do not fit either the definition of operand or option- 

32948 argument. However, for clarity, they have been included in the OPTIONS section, rather than 

32949 the OPERANDS section. 

32950 The definition of nice value is not intended to suggest that all processes in a system have 

32951 priorities that are comparable. Scheduling policy extensions such as the realtime priorities in 

32952 POSIX.4 make the notion of a single underlying priority for all scheduling policies problematic. 

32953 Some systems may implement the nice -related features to affect all processes on the system, 

32954 others to affect just the general time-sharing activities implied by this volume of 

32955 IEEE Std. 1003.1-200x, and others may have no effect at all. Because of the use of 

32956 "implementation-dependent” in nice and renice, a wide range of implementation strategies are 

32957 possible. 

32958 Originally, this utility was written in the historical manner, using the term "nice value". This 

32959 was always a point of concern with users because it was never intuitively obvious what this 

32960 meant. With a newer version of renice, which used the term "system scheduling priority", it was 

32961 hoped that novice users could better understand what this utility was meant to do. Also, it 

32962 would be easier to document what the utility was meant to do. Unfortunately, the addition of 

32963 the POSIX realtime scheduling capabilities introduced the concepts of process and thread 

32964 scheduling priorities that were totally unaffected by the nice/renice utilities or the 

32965 nice{)/setpriority () functions. Continuing to use the term "system scheduling priority" would 

32966 have incorrectly suggested that these utilities and functions were indeed affecting these realtime 

32967 priorities. It was decided to revert to the historical term "nice value" to reference this unrelated 

32968 process attribute. 

32969 Although this utility has use by system administrators (and in fact appears in the system 

32970 administration portion of the BSD documentation), the standard developers considered that it 

32971 was very useful for individual end users to control their own processes. 

32972 FUTURE DIRECTIONS 

32973 None. 
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32974 SEE ALSO 

32975 nice 

32976 CHANGE HISTORY 

32977 First released in Issue 4. 

32978 Issue 5 

32979 In the SYNOPSIS, an ellipsis is added to the -u option in all three obsolescent forms. 

32980 Issue 6 

32981 This utility is now marked as part of the User Portability Utilities option. 

32982 The APPLICATION USAGE section is added. 

32983 The obsolescent forms of the SYNOPSIS are removed. 

32984 Text previously conditional on POSIX_SAVED_IDS is mandatory in this issue. This is a FIPS 

32985 requirement. 
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32986 NAME 

32987 rm — remove directory entries 

32988 SYNOPSIS 

32989 rm [—fiRr] file. . . 


32990 DESCRIPTION 

32991 The rm utility shall remove the directory entry specified by each file argument. 


32992 If either of the files dot or dot-dot are specified as the basename portion of an operand (that is, 

32993 the final path name component), rm shall write a diagnostic message to standard error and do 

32994 nothing more with such operands. 

32995 For each file the following steps shall be taken: 


32996 


1. If the file does not exist: 


32997 

32998 

32999 


a. If the -f option is not specified, write a diagnostic message to standard error. 

b. Go on to any remaining/i/es. 

2. If file is of type directory, the following steps shall be taken: 


33000 

33001 


a. If neither the -R option nor the -r option is specified, write a diagnostic message to 
standard error, do nothing more with file, and go on to any remaining files. 


33002 

33003 

33004 

33005 

33006 


b. If the -f option is not specified, and either the permissions of file do not permit 
writing and the standard input is a terminal or the -i option is specified, write a 
prompt to standard error and read a line from the standard input. If the response is 
not affirmative, do nothing more with the current file and go on to any remaining 
files. 


33007 

33008 

33009 

33010 


c. For each entry contained in file, other than dot or dot-dot, the four steps listed here 
(1-4) shall be taken with the entry as if it were a file operand. The rm utility shall not I 
traverse directories by following symbolic links into other parts of the hierarchy, but I 
shall remove the links themselves. I 


33011 

33012 

33013 


d. If the -i option is specified, write a prompt to standard error and read a line from the 
standard input. If the response is not affirmative, do nothing more with the current 
file, and go on to any remaining files. 


33014 

33015 

33016 

33017 

33018 


3. If file is not of type directory, the -f option is not specified, and either the permissions of 
file do not permit writing and the standard input is a terminal or the -i option is specified, 
write a prompt to the standard error and read a line from the standard input. If the 
response is not affirmative, do nothing more with the current file and go on to any 
remaining files. 


33019 

33020 

33021 

33022 

33023 

33024 


4. If the current file is a directory, rm shall perform actions equivalent to the rmdir() function 
defined in the System Interfaces volume of IEEE Std. 1003.1-200x called with a path name 
of the current file used as the path argument. If the current file is not a directory, rm shall 
perform actions equivalent to the nnlink() function defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x called with a path name of the current file used as the path 
argument. 


33025 If this fails for any reason, rm shall write a diagnostic message to standard error, do 

33026 nothing more with the current file, and go on to any remaining files. 


33027 The rm utility shall be able to descend to arbitrary depths in a file hierarchy, and shall not fail 

33028 due to path length limitations (unless an operand specified by the user exceeds system 

33029 limitations). 
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33030 

33031 

33032 

33033 

33034 

33035 

33036 

33037 

33038 

33039 

33040 

33041 

33042 

33043 

33044 

33045 

33046 

33047 

33048 

33049 

33050 

33051 

33052 

33053 

33054 

33055 

33056 

33057 

33058 

33059 

33060 

33061 

33062 

33063 

33064 

33065 

33066 

33067 

33068 

33069 

33070 

33071 


OPTIONS 

The rm utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-f Do not prompt for confirmation. Do not write diagnostic messages or modify the 

exit status in the case of nonexistent operands. Any previous occurrences of the -i 
option shall be ignored. 

-i Prompt for confirmation as described previously. Any previous occurrences of the 

-f option shall be ignored. 

-R Remove file hierarchies. See the DESCRIPTION. 

-r Equivalent to -R. 

OPERANDS 

The following operand shall be supported: 

file A path name of a directory entry to be removed. 

STDIN 

Used to read an input line in response to each prompt specified in the STDOUT section. 

Otherwise, the standard input shall not be used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of rm: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes, and multi¬ 
character collating elements used in the extended regular expression defined for 
the yesexpr locale keyword in the LC_MESSAGES category. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments) and the behavior of character classes within regular expressions used 
in the extended regular expression defined for the yesexpr locale keyword in the 
LC_MESSAGES category. 

LC_MESSAGES 

Determine the locale for the processing of affirmative responses that should be 
used to affect the format and contents of diagnostic messages written to standard 
error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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33072 

33073 

33074 

33075 

33076 

33077 

33078 

33079 

33080 

33081 

33082 

33083 

33084 

33085 

33086 

33087 

33088 

33089 

33090 

33091 

33092 

33093 

33094 

33095 

33096 

33097 

33098 

33099 

33100 

33101 

33102 

33103 

33104 

33105 

33106 

33107 

33108 

33109 

33110 

33111 

33112 

33113 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Prompts shall be written to standard error under the conditions specified in the DESCRIPTION 
and OPTIONS sections. The prompts shall contain the file path name, but their format is 
otherwise unspecified. The standard error also shall be used for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 All of the named directory entries for which rm performed actions equivalent to rmdir () or I 
unlink{) functions were removed. I 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The rm utility is forbidden to remove the names dot and dot-dot in order to avoid the 
consequences of inadvertently doing something like: 

rm —r .* 

Some systems do not permit the removal of the last link to an executable binary file that is being 
executed; see the [EBUSY] error in the unlink () function defined in the System Interfaces volume 
of IEEE Std. 1003.1-200x. Thus, the rm utility can fail to remove such files. 

The -i option causes rm to prompt and read the standard input even if the standard input is not 
a terminal, but in the absence of -i the mode prompting is not done when the standard input is 
not a terminal. 

EXAMPLES 

1. The following command: 

rm a . out core 

removes the directory entries: a.out and core. 

2. The following command: 

rm —Rf junk 

removes the directory junk and all its contents, without prompting. 

RATIONALE 

The -i option causes rm to prompt and read the standard input even if the standard input is not 
a terminal, but, in the absence of -i, the mode prompting is not done when the standard input is 
not a terminal. 

For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of rm describing the behavior 
when prompting for confirmation, should be interpreted in the following manner: 
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33114 if ( (NOT f_option) AND 

33115 ( (not_writable AND input_is_terminal) OR i_option) ) 

33116 The exact format of the interactive prompts is unspecified. Only the general nature of the 

33117 contents of prompts are specified because implementations may desire more descriptive 

33118 prompts than those used on historical implementations. Therefore, an application not using the 

33119 -f option, or using the -i option, relies on the system to provide the most suitable dialog directly 

33120 with the user, based on the behavior specified. 

33121 The -r option is historical practice on all known systems. The synonym -R option is provided 

33122 for consistency with the other utilities in this volume of IEEE Std. 1003.1-200x that provide 

33123 options requesting recursive descent through the file hierarchy. 

33124 The behavior of the -f option in historical versions of rm is inconsistent. In general, along with 

33125 "forcing" the unlink without prompting for permission, it always causes diagnostic messages to 

33126 be suppressed and the exit status to be unmodified for nonexistent operands and files that 

33127 cannot be unlinked. In some versions, however, the -f option suppresses usage messages and 

33128 system errors as well. Suppressing such messages is not a service to either shell scripts or users. 

33129 It is less clear that error messages regarding unlinkable files should be suppressed. Although this 

33130 is historical practice, this volume of IEEE Std. 1003.1-200x does not permit the -f option to 

33131 suppress such messages. 

33132 When given the -r and -i options, historical versions of rm prompt the user twice for each 

33133 directory, once before removing its contents and once before actually attempting to delete the 

33134 directory entry that names it. This allows the user to "prune" the file hierarchy walk. Historical 

33135 versions of rm were inconsistent in that some did not do the former prompt for directories 

33136 named on the command line and others had obscure prompting behavior when the -i option 

33137 was specified and the permissions of the file did not permit writing. The POSIX Shell and 

33138 Utilities rm differs little from historic practice, but does require that prompts be consistent. 

33139 Historical versions of rm were also inconsistent in that prompts were done to both standard 

33140 output and standard error. This volume of IEEE Std. 1003.1-200x requires that prompts be done 

33141 to standard error, for consistency with cp and mv, and to allow historical extensions to rm that 

33142 provide an option to list deleted files on standard output. 

33143 The rm utility is required to descend to arbitrary depths so that any file hierarchy may be 

33144 deleted. This means, for example, that the rm utility cannot run out of file descriptors during its 

33145 descent (that is, if the number of file descriptors is limited, rm cannot be implemented in the 

33146 historical fashion where one file descriptor is used per directory level). Also, rm is not permitted 

33147 to fail because of path length restrictions, unless an operand specified by the user is longer than 

33148 |PATH_MAX}. I 

33149 The rm utility removes symbolic links themselves, not the files they refer to, as a consequence of I 

33150 the dependence on the unlink() functionality, per the DESCRIPTION. When removing I 

33151 hierarchies with -r or -R, the prohibition on following symbolic links has to be made explicit. I 

33152 FUTURE DIRECTIONS 

33153 None. I 

33154 SEE ALSO 

33155 rmdir, the System Interfaces volume of IEEE Std. 1003.1-200x, remove (), unlink{) 

33156 CHANGE HISTORY 

33157 First released in Issue 2. 
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33158 

33159 

33160 

33161 

33162 

33163 

33164 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

FUTURE DIRECTIONS section added. I 

Issue 6 I 

Text is added to clarify actions relating to symbolic links as specified in the IEEE P1003.2b draft I 
standard. I 
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33165 

33166 

33167 

33168 

33169 

33170 

33171 

33172 

33173 

33174 

33175 

33176 

33177 

33178 

33179 

33180 

33181 

33182 

33183 

33184 

33185 

33186 

33187 

33188 

33189 

33190 

33191 

33192 

33193 

33194 

33195 

33196 

33197 

33198 

33199 

33200 

33201 

33202 

33203 

33204 

33205 

33206 

33207 


NAME 

rmdel — remove a delta from an SCCS file (DEVELOPMENT) 

SYNOPSIS 

xsi rmdel —r SID file. . . 

DESCRIPTION 

The rmdel utility shall remove the delta specified by the SID from each named SCCS file. The I 
delta to be removed shall be the most recent delta in its branch in the delta chain of each named I 
SCCS file. In addition, the application shall ensure that the SID specified is not that of a version I 
being edited for the purpose of making a delta; that is, if a p-file (see get on page 510) exists for I 
the named SCCS file, the SID specified shall not appear in any entry of the p-file . I 

Removal of a delta is restricted to: 

1. The user who made the delta 

2. The owner of the SCCS file 

3. The owner of the directory containing the SCCS file 

OPTIONS 

The rmdel utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following option shall be supported: 

-r SID Specify the SCCS identification string {SID) of the delta to be deleted. 

OPERANDS 

The following operand shall be supported: 

file A path name of an existing SCCS file or a directory. If file is a directory, rmdel 

behaves as though each file in the directory were specified as a named file, except 
that non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files are silently ignored. 

If a single instance file is specified as , the standard input is read; each line of 
the standard input is taken to be the name of an SCCS file to be processed. Non- 
SCCS files and unreadable files are silently ignored. 

STDIN 

The standard input shall be a text file used only when the file operand is specified as ' - '. Each I 
line of the text file shall be interpreted as an SCCS path name. 

INPUT FILES 

The SCCS files are files of unspecified format. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of rmdel: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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33208 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

33209 characters (for example, single-byte as opposed to multi-byte characters in 

33210 arguments and input files). 

33211 LC_MESSAGES 

33212 Determine the locale that should be used to affect the format and contents of 

33213 diagnostic messages written to standard error. 

33214 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

33215 ASYNCHRONOUS EVENTS 

33216 Default. 

33217 STDOUT 

33218 Not used. 

33219 STDERR 

33220 Used only for diagnostic messages. 

33221 OUTPUT FILES 

33222 The SCCS files are files of unspecified format. During processing of a file, a temporary x-file, as 

33223 described in admin on page 160, may be created and deleted; a locking z-file, as described in get 

33224 on page 510, may be created and deleted. 

33225 EXTENDED DESCRIPTION 

33226 None. 

33227 EXIT STATUS 

33228 The following exit values shall be returned: 

33229 0 Successful completion. 

33230 >0 An error occurred. 

33231 CONSEQUENCES OF ERRORS 

33232 Default. 

33233 APPLICATION USAGE 

33234 None. 

33235 EXAMPLES 

33236 None. 

33237 RATIONALE 

33238 None. 

33239 FUTURE DIRECTIONS 

33240 None. 

33241 SEE ALSO 

33242 delta, get, prs 

33243 CHANGE HISTORY 

33244 First released in Issue 2. 

33245 Issue 4 

33246 Format reorganized. 

33247 Utility Syntax Guidelines support mandated. 

33248 Internationalized environment variable support mandated. 
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33249 Issue 6 

33250 The normative text is reworded to avoid use of the term "must” for application requirements. 


Commands and Utilities, Issue 6 


867 



rmdir 


Utilities 


33251 

33252 

33253 

33254 

33255 

33256 

33257 

33258 

33259 

33260 

33261 

33262 

33263 

33264 

33265 

33266 

33267 

33268 

33269 

33270 

33271 

33272 

33273 

33274 

33275 

33276 

33277 

33278 

33279 

33280 

33281 

33282 

33283 

33284 

33285 

33286 

33287 

33288 

33289 

33290 

33291 

33292 


NAME 

rmdir — remove directories 

SYNOPSIS 

rmdir [—p] dir. . . 

DESCRIPTION 

The rmdir utility shall remove the directory entry specified by each dir operand, which the 
application shall ensure refers to an empty directory. 

Directories shall be processed in the order specified. If a directory and a subdirectory of that 
directory are specified in a single invocation of the rmdir utility, the application shall specify the 
subdirectory before the parent directory so that the parent directory will be empty when the 
rmdir utility tries to remove it. 

OPTIONS 

The rmdir utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

The following option shall be supported: 

-p Remove all directories in a path name. For each dir operand: 

1. The directory entry it names shall be removed. 

2. If the dir operand includes more than one path name component, effects 
equivalent to the following command shall occur: 

rmdir —p $(dirname dir) 

OPERANDS 

The following operand shall be supported: 

dir A path name of an empty directory to be removed. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of rmdir: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 
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33293 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

33294 ASYNCHRONOUS EVENTS 

33295 Default. 

33296 STDOUT 

33297 Not used. 

33298 STDERR 

33299 Used only for diagnostic messages. 

33300 OUTPUT FILES 

33301 None. 

33302 EXTENDED DESCRIPTION 

33303 None. 

33304 EXIT STATUS 

33305 The following exit values shall be returned: 

33306 0 Each directory entry specified by a dir operand was removed successfully. 

33307 >0 An error occurred. 

33308 CONSEQUENCES OF ERRORS 

33309 Default. 

33310 APPLICATION USAGE 

33311 The definition of an empty directory is one that contains, at most, directory entries for dot and 

33312 dot-dot. 

33313 EXAMPLES 

33314 If a directory a in the current directory is empty except it contains a directory b and a/b is empty 

33315 except it contains a directory c: 

33316 rmdir —p a/b/c 

33317 removes all three directories. 

33318 RATIONALE 

33319 On historical System V systems, the -p option also caused a message to be written to the 

33320 standard output. The message indicated whether the whole path was removed or whether part 

33321 of the path remained for some reason. The STDERR section requires this diagnostic when the 

33322 entire path specified by a dir operand is not removed, but does not allow the status message 

33323 reporting success to be written as a diagnostic. 

33324 The rmdir utility on System V also included an -s option that suppressed the informational 

33325 message output by the -p option. This option has been omitted because the informational 

33326 message is not specified by this volume of IEEE Std. 1003.1-200x. 

33327 FUTURE DIRECTIONS 

33328 None. 

33329 SEE ALSO 

33330 rm, the System Interfaces volume of IEEE Std. 1003.1-200x, remove (), rmdir (), unlink () 

33331 CHANGE HISTORY 

33332 First released in Issue 2. 
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33333 Issue 4 

33334 Separated from the rm description and aligned with the ISO/IEC 9945-2:1993 standard. 

33335 Issue 6 

33336 The normative text is reworded to avoid use of the term "must” for application requirements. 
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33337 NAME 

33338 sact — print current SCCS file-editing activity (DEVELOPMENT) 

33339 SYNOPSIS 

33340 xsi sact file. . . 

33341 

33342 DESCRIPTION 

33343 The sact utility shall inform the user of any impending deltas to a named SCCS file by writing a 

33344 list to standard output. This situation occurs when get -e has been executed previously without 

33345 a subsequent execution of delta. 

33346 OPTIONS 

33347 None. 


33348 OPERANDS 

33349 The following operand shall be supported: 

33350 file A path name of an existing SCCS file or a directory. If file is a directory, sact 

33351 behaves as though each file in the directory were specified as a named file, except 

33352 that non-SCCS files (last component of the path name does not begin with s.) and 

33353 unreadable files are silently ignored. 

33354 If a single instance file is specified as ' , the standard input is read; each line of 

33355 the standard input shall be taken to be the name of an SCCS file to be processed. 

33356 Non-SCCS files and unreadable files shall be silently ignored. 

33357 STDIN 

33358 The standard input shall be a text file used only when the file operand is specified as ' - '. Each I 

33359 line of the text file shall be interpreted as an SCCS path name. 

33360 INPUT FILES 

33361 Any SCCS files interrogated are files of an unspecified format. 


33362 ENVIRONMENT VARIABLES 

33363 The following environment variables shall affect the execution of sact : 


33364 

33365 

33366 

33367 

33368 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


33369 

33370 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


33371 

33372 

33373 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


33374 LC_MESSAGES 

33375 Determine the locale that should be used to affect the format and contents of 

33376 diagnostic messages written to standard error. 


33377 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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33378 

33379 

33380 

33381 

33382 

33383 

33384 

33385 

33386 

33387 

33388 

33389 

33390 

33391 

33392 

33393 

33394 

33395 

33396 

33397 

33398 

33399 

33400 

33401 

33402 

33403 

33404 

33405 

33406 

33407 

33408 

33409 

33410 

33411 

33412 

33413 

33414 

33415 


ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The output for each named file shall consist of a line in the following format: 

"%sA%sA%sA%sA%s\n" , <SID>, <new SID>, <login>, <date>, <time> 

<SID> Specifies the SID of a delta that currently exists in the SCCS file to which changes 

are made to make the new delta. 

<neiv SID> Specifies the SID for the new delta to be created. 

<login> Contains the login name of the user who makes the delta (that is, who executed a 
get for editing). 

<date> Contains the date that get -e was executed, in the format used by the prs :D: data 

keyword. 

<time> Contains the time that get -e was executed, in the format used by the prs :T: data 

keyword. 

If there is more than one named file or if a directory or standard input is named, each path name 
shall be written before each of the preceding lines: 

"\n%s:\n", <pathname> 

STDERR 

Used only for optional informative messages concerning SCCS files with no impending deltas, 
and for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 
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33416 SEE ALSO 

33417 delta, get, unget 

33418 CHANGE HISTORY 

33419 First released in Issue 2. 

33420 Issue 4 

33421 Format reorganized. 

33422 Utility Syntax Guidelines support mandated. 

33423 Internationalized environment variable support mandated. 

33424 Issue 4, Version 2 

33425 The STDERR section encompasses informative messages concerning SCCS files with no 

33426 impending deltas. 
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33427 NAME 

33428 sees — front end for the SCCS subsystem (DEVELOPMENT) 

33429 SYNOPSIS 

33430 xsi sees [—r] [—d path ] [—p path ] command [options. . .] [operands. . .] 

33431 

33432 DESCRIPTION 

33433 The secs utility is a front end to the SCCS programs. It also includes the capability to run set- 

33434 user-id to another user to provide additional protection. 

33435 The sees utility shall invoke the specified command with the specified options and operands . By 

33436 default, each of the operands shall be modified by prefixing it with the string SCCS/s.. 

33437 The command operand can be one of the SCCS utilities in this volume of IEEE Std. 1003.1-200x 

33438 (admin, delta, get, prs, rmdel, sact, unget, val, or what) or one of the pseudo-utilities listed in the 

33439 EXTENDED DESCRIPTION section. 


33440 OPTIONS 

33441 The sccs utility shall conform to the System Interface Definitions volume of I 

33442 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except that options operands are I 

33443 actually options to be passed to the utility named by command. When the portion of the 

33444 command: 


33445 command [options ... ] [operands ... ] 


33446 is considered, all of the pseudo-utilities used as command shall support the Utility Syntax 

33447 Guidelines. Any of the other SCCS utilities that can be invoked in this manner support the 

33448 Guidelines to the extent indicated by their individual OPTIONS sections. 

33449 The following options shall be supported preceding the command operand: 


33450 

33451 

33452 


-d path A path name of a directory to be used as a root directory for the SCCS files. The 
default is the current directory. The -d option takes precedence over the 
PROJECTDIR variable. See -p. 


33453 

33454 


-p path A path name of a directory in which the SCCS files are located. The default is the 
SCCS directory. 


33455 

33456 

33457 


The -p option differs from the -d option in that the -d option-argument is 
prefixed to the entire path name and the -p option-argument is inserted before the 
final component of the path name. For example: 


33458 


sccs —d /x —p y get a/b 


33459 


converts to: 


33460 


get /x/a/y/s.b 


33461 


This allows the creation of aliases such as: 


33462 

33463 


alias syssccs="sccs -d /usr/src" 

which is used as: 


33464 


syssccs get cmd/who.c 


33465 -r 

33466 

33467 

33468 


Invoke command with the real user ID of the process, not any effective user ID that 
the sccs utility is set to. Certain commands (admin, check, clean, diffs, info, rmdel, 
and tell) cannot be run set-user-ID by all users, since this would allow anyone to 
change the authroizations. These commands are always run as the real user. 
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33469 OPERANDS 

33470 The following operands shall be supported: 


33471 

33472 


command An SCCS utility name or the name of one of the pseudo-utilities listed in the 
EXTENDED DESCRIPTION section. 


33473 options An option or option-argument to be passed to command. 

33474 operands An operand to be passed to command. 

33475 STDIN 

33476 See the utility description for the specified command. 

33477 INPUT FILES 

33478 See the utility description for the specified command. 


33479 ENVIRONMENT VARIABLES 

33480 The following environment variables shall affect the execution of sees: 


33481 

33482 

33483 

33484 

33485 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


33486 LC_ALL If set to a non-empty string value, override the values of all the other 

33487 internationalization variables. 


33488 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

33489 characters (for example, single-byte as opposed to multi-byte characters in 

33490 arguments and input files). 

33491 LC_MESSAGES 

33492 Determine the locale that should be used to affect the format and contents of 

33493 diagnostic messages written to standard error. 

33494 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

33495 PROJECTDIR 

33496 Provide a default value for the -d path option. If the value of PROJECTDIR begins 

33497 with a slash, it shall be considered an absolute path name; otherwise, the value of 

33498 PROJECTDIR is treated as a user name and that user's initial working directory 

33499 shall be examined for a subdirectory sre or source. If such a directory is found, it 

33500 shall be used. Otherwise, the value shall be used as a relative path name. 

33501 Additional environment variable effects may be found in the utility description for the specified 

33502 command. 


33503 ASYNCHRONOUS EVENTS 

33504 Default. 


33505 STDOUT 

33506 See the utility description for the specified command. 

33507 STDERR 

33508 See the utility description for the specified command. 
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33509 

33510 

33511 

33512 

33513 

33514 

33515 

33516 

33517 

33518 

33519 

33520 

33521 

33522 

33523 

33524 

33525 

33526 

33527 

33528 

33529 

33530 

33531 

33532 

33533 

33534 

33535 

33536 

33537 

33538 

33539 

33540 

33541 

33542 

33543 

33544 

33545 

33546 

33547 

33548 

33549 

33550 


OUTPUT FILES 

See the utility description for the specified command. 

EXTENDED DESCRIPTION 

The following pseudo-utilities are supported as command operands. All options referred to in the 

following list are values given in the options operands following command. 

check Equivalent to info, except that nothing is printed if nothing is being edited, and a non¬ 
zero exit status is returned if anything is being edited. The intent is to have this 
included in an "install" entry in a makefile to ensure that everything is included into 
the SCCS file before a version is installed. 

clean Remove everything from the current directory that can be recreated from SCCS files, 
but do not remove any files being edited. If the -b option is given, branches are ignored 
in the determination of whether they are being edited; this is dangerous if branches are 
kept in the same directory. 

create Create an SCCS file, taking the initial contents from the file of the same name. Any 
options to admin are accepted. If the creation is successful, the original files are 
renamed by prefixing the basenames with a comma. These renamed files should be 
removed after it has been verified that the SCCS files have been created successfully. 

delget Perform a delta on the named files and then get new versions. The new versions have ID 
keywords expanded and are not editable. Any -m, -p, -r, -s, and -y options are passed 
to delta, and any -b, -c, -e, -i, -k, -1, -s, and -x options are passed to get. 

deledit Equivalent to delget, except that the get phase includes the -e option. This option is 
useful for making a checkpoint of the current editing phase. The same options are 
passed to delta as described above, and all the options listed forget above except -e are 
passed to edit. 

diffs Write a difference listing between the current version of the files checked out for 
editing and the versions in SCCS format. Any -r, -c, -i, -x, and -t options are passed to 
get; any -1, -s, -e, -f, -h, and -b options are passed to diff. A -C option is passed to diff 
as -c. 

edit Equivalent to get -e. 

fix Remove the named delta, but leave a copy of the delta with the changes that were in it. 

It is useful for fixing small compiler bugs, and so on. The application shall ensure that it I 
is followed by a -r SID option. Since fix doesn't leave audit trails, it should be used I 
carefully. 

info Write a listing of all files being edited. If the -b option is given, branches (that is, SIDs 
with two or fewer components) are ignored. If a -u user option is given, then only files 
being edited by the named user are listed. A -U option is equivalent to 
-u <current user>. 

print Write out verbose information about the named files, equivalent to sees prs. 

tell Write a <newline>-separated list of the files being edited to standard output. Takes the 
-b, -u, and -U options like info and check. 

unedit This is the opposite of an edit or a get -e. It should be used with caution, since any 
changes made since the get are lost. 
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33551 EXIT STATUS 

33552 The following exit values shall be returned: 

33553 0 Successful completion. 

33554 >0 An error occurred. 

33555 CONSEQUENCES OF ERRORS 

33556 Default. 

33557 APPLICATION USAGE 

33558 Many of the SCCS utilities take directory names as operands as well as specific file names. The 

33559 pseudo-utilities supported by sees are not described as having this capability, but are not 

33560 prohibited from doing so. 

33561 EXAMPLES 

33562 1. 

33563 

33564 

33565 

33566 2. 

33567 

33568 

33569 

33570 3. 

33571 

33572 4. 

33573 

33574 5. 

33575 

33576 6. 

33577 

33578 

33579 

33580 RATIONALE 

33581 None. 

33582 FUTURE DIRECTIONS 

33583 None. 

33584 SEE ALSO 

33585 admin , delta , get , make, prs, rmdel, sact, unget, val, zvhat 

33586 CHANGE HISTORY 

33587 First released in Issue 4. 


To get a file for editing, edit it and produce a new delta: 

sees get —e file.c 

ex file.c 

sees delta file.c 

To get a file from another directory: 

secs —p /usr/src/sccs/s. get cc.c 
or: 

sees get /usr/src/sccs/s.cc.c 

To make a delta of a large number of files in the current directory: 

sees delta *.c 

To get a list of files being edited that are not on branches: 

secs info —b 

To delta everything being edited by the current user: 

sees delta $(secs tell —U) 

In a makefile, to get source files from an SCCS file if it does not already exist: 

SRCS = <list of source files> 

$(SRCS): 

sees get $(REL) $@ 


Commands and Utilities, Issue 6 


877 



sees 


Utilities 


33588 

33589 

33590 

33591 

33592 


Issue 6 

In the ENVIRONMENT VARIABLES section, the PROJECTDIR description is updated from 
"otherwise, the home directory of a user of that name is examined" to "otherwise, the value of 
PROJECTDIR is treated as a user name and that user's initial working directory is examined". 

The normative text is reworded to avoid use of the term "must" for application requirements. 


878 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


sed 


33593 NAME 

33594 sed — stream editor 


33595 SYNOPSIS 

33596 sed [—n] script[file...] 


33597 sed [—n] [—e script ] . . . [—f script_file ] . . . [file. . . ] 


33598 DESCRIPTION 

33599 The sed utility is a stream editor that shall read one or more text files, make editing changes 

33600 according to a script of editing commands, and write the results to standard output. The script 

33601 shall be obtained from either the script operand string or a combination of the option-arguments 

33602 from the -e script and -f script Jile options. 

33603 OPTIONS 

33604 The sed utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

33605 Section 12.2, Utility Syntax Guidelines, except that the order of presentation of the -e and -f I 

33606 options is significant. 

33607 The following options shall be supported: 

33608 -e script Add the editing commands specified by the script option-argument to the end of 

33609 the script of editing commands. The script option-argument shall have the same 

33610 properties as the script operand, described in the OPERANDS section. 

33611 -f script_file Add the editing commands in the file script_file to the end of the script. 

33612 -n Suppress the default output (in which each line, after it is examined for editing, is 

33613 written to standard output). Only lines explicitly selected for output are written. 

33614 Multiple -e and -f options may be specified. All commands shall be added to the script in the 

33615 order specified, regardless of their origin. 


33616 OPERANDS 

33617 The following operands shall be supported: 


33618 file 

33619 

33620 

33621 


A path name of a file whose contents are read and edited. If multiple file operands 
are specified, the named files shall be read in the order specified and the 
concatenation shall be edited. If no file operands are specified, the standard input 
shall be used. 


33622 

33623 

33624 


script A string to be used as the script of editing commands. The application shall not I 

present a script that violates the restrictions of a text file except that the final I 
character need not be a <newline> character. 


33625 STDIN 

33626 The standard input shall be used only if no file operands are specified. See the INPUT FILES 

33627 section. 


33628 INPUT FILES 

33629 The input files shall be text files. The script_files named by the -f option shall consist of editing I 

33630 commands. I 


33631 ENVIRONMENT VARIABLES 

33632 The following environment variables shall affect the execution of sed: 

33633 LANG Provide a default value for the internationalization variables that are unset or null. 

33634 If LANG is unset or null, the corresponding value from the implementation- 

33635 dependent default locale shall be used. If any of the internationalization variables 

33636 contains an invalid setting, the utility shall behave as if none of the variables had 
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33637 been defined. 

33638 LC_ALL If set to a non-empty string value, override the values of all the other 

33639 internationalization variables. 

33640 LC JCOLLATE 

33641 Determine the locale for the behavior of ranges, equivalence classes, and multi- 

33642 character collating elements within regular expressions. 

33643 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

33644 characters (for example, single-byte as opposed to multi-byte characters in 

33645 arguments and input files), and the behavior of character classes within regular 

33646 expressions. 

33647 LC_MESSAGES 

33648 Determine the locale that should be used to affect the format and contents of 

33649 diagnostic messages written to standard error. 

33650 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

33651 ASYNCHRONOUS EVENTS 

33652 Default. 

33653 STDOUT 

33654 The input files shall be written to standard output, with the editing commands specified in the 

33655 script applied. If the -n option is specified, only those input lines selected by the script shall be 

33656 written to standard output. 

33657 STDERR 

33658 Used only for diagnostic messages. 

33659 OUTPUT FILES 

33660 The output files shall be text files whose formats are dependent on the editing commands given. 

33661 EXTENDED DESCRIPTION 

33662 The script shall consist of editing commands of the following form: 

33663 [address [, address] ] function 

33664 where function represents a single-character command verb from the list in Editing Commands 

33665 in sed on page 881, followed by any applicable arguments. 

33666 Zero or more <blank>s shall be accepted before the first address and before function. Any 

33667 number of semicolons shall be accepted before the first address. 

33668 In default operation, sed cyclically shall copy a line of input, less its terminating <newline>, into 

33669 a pattern space (unless there is something left after a D command), apply in sequence all 

33670 commands whose addresses select that pattern space, and at the end of the script copy the 

33671 pattern space to standard output (except when -n is specified) and delete the pattern space. 

33672 Whenever the pattern space is written to standard output or a named file, sed shall immediately 

33673 follow it with a <newline>. 

33674 Some of the editing commands use a hold space to save all or part of the pattern space for 

33675 subsequent retrieval. The pattern and hold spaces shall each be able to hold at least 8192 bytes. 
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33676 

33677 

33678 

33679 

33680 

33681 

33682 

33683 

33684 

33685 

33686 

33687 

33688 

33689 

33690 

33691 

33692 

33693 

33694 

33695 

33696 

33697 

33698 

33699 

33700 

33701 

33702 

33703 

33704 

33705 

33706 

33707 

33708 

33709 

33710 

33711 

33712 

33713 

33714 

33715 

33716 

33717 
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Addresses in sed 

An address is either a decimal number that counts input lines cumulatively across files, a ' $' 
character that addresses the last line of input, or a context address (which consists of a BRE, as 
described in Regular Expressions in sed, preceded and followed by a delimiter, usually a slash). 

An editing command with no addresses shall select every pattern space. 

An editing command with one address shall select each pattern space that matches the address. 

An editing command with two addresses shall select the inclusive range from the first pattern 
space that matches the first address through the next pattern space that matches the second. (If 
the second address is a number less than or equal to the line number first selected, only one line 
shall be selected.) Starting at the first line following the selected range, sed shall look again for 
the first address. Thereafter, the process shall be repeated. Omitting either or both of the address 
components in the following form produces undefined results: 

[address[,address]] 


Regular Expressions in sed 

The sed utility shall support the BREs described in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 9.3, Basic Regular Expressions, with the following additions: 

• In a context address, the construction "\cBREc", where c is any character other than 
backslash or <newline>, shall be identical to "/BRE/". If the character designated by c 
appears following a backslash, then it shall be considered to be that literal character, which 
shall not terminate the BRE. For example, in the context address " .me I the second x stands 

for itself, so that the BRE is " abcxde f ". 

• The escape sequence ' \n' shall match a <newline> embedded in the pattern space. A literal 
<newline> character shall not be used in the BRE of a context address or in the substitute 
function. 

• If an RE is empty (that is, no pattern is specified) sed shall behave as if the last RE used in the 
last command applied (either as an address or as part of a substitute command) was 
specified. 

Editing Commands in sed 

In the following list of editing commands, the maximum number of permissible addresses for 
each function is indicated by [Oaddr], [lciddr], or [2nddr], representing zero, one, or two 
addresses. 

The argument text shall consist of one or more lines. Each embedded <newline> in the text shall 
be preceded by a backslash. Other backslashes in text shall be removed, and the following 
character shall be treated literally. 

The r and w command verbs, and the zv flag to the s command, take an optional rfile (or wfile) 
parameter, separated from the command verb letter or flag by one or more <blank>s; 
implementations may allow zero separation as an extension. 

The argument rfile or the argument wfile shall terminate the editing command. Each wfile shall be 
created before processing begins. Implementations shall support at least ten wfile arguments in 
the script; the actual number (greater than or equal to 10) that shall be supported by the 
implementation is unspecified. The use of the wfile parameter shall cause that file to be initially 
created, if it does not exist, or shall replace the contents of an existing file. 
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The b, r, s, t, w, y, and : command verbs shall accept additional arguments. The following I 
synopses indicate which arguments shall be separated from the command verbs by a single I 
<space>. I 

The a and r commands schedule text for later output. The text specified for the a command, and I 
the contents of the file specified for the r command, shall be written to standard output just I 
before the next attempt to fetch a line of input when executing the N or n commands, or when I 
reaching the end of the script. If written when reaching the end of the script, and the -n option I 
was not specified, the text shall be written after copying the pattern space to standard output. I 
The contents of the file specified for the r command shall be as of the time the output is written, I 
not the time the r command is applied. The text shall be output in the order in which the a and r I 
commands were applied to the input. I 

Command verbs other than {, a, b, c, i, r, t, w,:, and # can be followed by a semicolon, optional I 
<blank>s, and another command verb. However, when the s command verb is used with the zv I 
flag, following it with another command in this manner produces undefined results. I 

A function can be preceded by one or more ' !' characters, in which case the function shall be I 
applied if the addresses do not select the pattern space. Zero or more <blank>s shall be accepted I 
before the first ' !' character. It is unspecified whether <blank> characters can follow a ' !' I 
character, and conforming applications shall not follow a ' !' character with <blank>s. I 

[2addr] {function I 

function I 

} Execute a list of sed functions only when the pattern space is selected. The list of I 

sed functions shall be surrounded by braces and separated by <newline>s, as I 
follows. The braces can be preceded or followed by <blank>s. The functions can I 
be preceded by <blank>s, but shall not be followed by <blank>s. The cright- I 
brace> shall be preceded by a <newline> and can be preceded or followed by I 
<blank>s. I 

[laddr]a\ I 

text Write text to standard output as described previously. I 

[2addr] b [label] I 

Branch to the : function bearing the label . If label is not specified, branch to the end I 
of the script. The implementation shall support labels recognized as unique up to 
at least 8 characters; the actual length (greater than or equal to 8) that shall be 
supported by the implementation is unspecified. It is unspecified whether 
exceeding a label length causes an error or a silent truncation. I 

I 

Delete the pattern space. With a 0 or 1 address or at the end of a 2-address range, I 
place text on the output and start the next cycle. I 

Delete the pattern space and start the next cycle. 

Delete the initial segment of the pattern space through the first <newline> and I 
start the next cycle. I 

Replace the contents of the pattern space by the contents of the hold space. 

Append to the pattern space a <newline> followed by the contents of the hold I 
space. I 

Replace the contents of the hold space with the contents of the pattern space. 


[2addr]c\ 

text 

[2addr] d 
[2addr] D 

[2addr] g 
[2addr] G 

[2addr] h 
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33763 

33764 

[2addr] H 

Append to the hold space a <newline> followed by the contents of the pattern 
space. 

33765 

33766 

[laddr] i\ 
text 

Write text to standard output. 

33767 

33768 

33769 

33770 

33771 

33772 

33773 

33774 

33775 

[2addr] 1 

(The letter ell.) Write the pattern space to standard output in a visually 
unambiguous form. The characters listed in the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, Table 5-1, Escape Sequences and Associated 
Actions (' \\ ', '\a', ' \b', '\f', '\r', '\t', ' \v') shall be written as the 
corresponding escape sequence; the ' \n' in that table is not applicable. Non- 
printable characters not in that table shall be written as one three-digit octal 
number (with a preceding backslash) for each byte in the character (most 
significant byte first). If the size of a byte on the system is greater than 9 bits, the 
format used for non-printable characters is implementation-dependent. 

33776 

33777 

33778 

33779 


Long lines shall be folded, with the point of folding indicated by writing a 
backslash followed by a <newline>; the length at which folding occurs is 
unspecified, but should be appropriate for the output device. The end of each line 
shall be marked with a ' $'. 

33780 

33781 

[2addr] n 

Write the pattern space to standard output if the default output has not been 
suppressed, and replace the pattern space with the next line of input. 

33782 

33783 


If no next line of input is available, the n command verb shall branch to the end of 
the script and quit without starting a new cycle. 

33784 

33785 

33786 

[2addr] N 

Append the next line of input to the pattern space, using an embedded <newline> 
character to separate the appended material from the original material. Note that 
the current line number changes. 

33787 

33788 

33789 


If no next line of input is available, the N command verb shall branch to the end of 
the script and quit without starting a new cycle or copying the pattern space to 
standard output. 

33790 

[2addr] p 

Write the pattern space to standard output. 

33791 

[2addr] P 

Write the pattern space, up to the first <newline>, to standard output. 

33792 

[laddr] q 

Branch to the end of the script and quit without starting a new cycle. 

33793 

33794 

33795 

[laddr] r r/i/e 

Copy the contents of rfile to standard output as described previously. If rfile does 
not exist or cannot be read, it shall be treated as if it were an empty file, causing no 
error condition. 

33796 

33797 

33798 

33799 

33800 

33801 

[2addr]s/BRE/replacement/flags 

Substitute the replacement string for instances of the BRE in the pattern space. Any 
character other than backslash or <newline> can be used instead of a slash to 
delimit the BRE and the replacement. Within the BRE and the replacement, the 
BRE delimiter itself can be used as a literal character if it is preceded by a 
backslash. 

33802 

33803 

33804 

33805 

33806 

33807 

33808 


An ampersand (' &' ) appearing in the replacement shall be replaced by the string 
matching the BRE. The special meaning of ' &' in this context can be suppressed 
by preceding it by a backslash. The characters ' \n', where n is a digit, shall be 
replaced by the text matched by the corresponding backreference expression. For 
each backslash (' V ) encountered in scanning replacement from beginning to end, 
the backslash shall be discarded and the following character shall lose its special 
meaning (if any). It is unspecified what special meaning is given to any character 
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other than ' &', ' \, or digits. I 

A line can be split by substituting a <newline> character into it. The application I 
shall escape the <newline> in the replacement by preceding it by a backslash. A I 
substitution shall be considered to have been performed even if the replacement I 
string is identical to the string that it replaces. Any backslash used to alter the I 
default meaning of a subsequent character shall be discarded from the BRE or the I 
replacement before evaluating the BRE or using the replacement. I 

The value of flags shall be zero or more of: I 

n Substitute for the nth occurrence only of the BRE found within the I 

pattern space. I 

g Globally substitute for all non-overlapping instances of the BRE I 

rather than just the first one. If both g and n are specified, the results I 
are unspecified. 

p Write the pattern space to standard output if a replacement was 

made. 

w wfile Write. Append the pattern space to wfile if a replacement was made. I 
A conforming application shall precede the wfile argument with one I 
or more <blank>s. If the zv flag is not the last flag value given in a I 
concatenation of multiple flag values, the results are undefined. I 

[2addr ]t [label] 

Test. Branch to the : command verb bearing the label if any substitutions have been I 
made since the most recent reading of an input line or execution of a t. If label is 
not specified, branch to the end of the script. 

[2addr] w wfile 

Append {write) the pattern space to wfile . I 

[2addr]x Exchange the contents of the pattern and hold spaces. 

[2addr]ylstringllstring2l 

Replace all occurrences of characters in stringl with the corresponding characters 
in string2. If a backslash followed by an n appear in stringl or string2, the two I 

characters shall be handled as a single <newline> character. If the number of I 

characters in stringl and string2 are not equal, or if any of the characters in stringl I 

appear more than once, the results are undefined. Any character other than 
backslash or <newline> can be used instead of slash to delimit the strings. If the I 

delimiter is not n, within stringl and string2, the delimiter itself can be used as a I 

literal character if it is preceded by a backslash. If a backslash character is I 

immediately followed by a backslash character in stringl or string2, the two I 

backslash characters shall be counted as a single literal backslash character. The I 

meaning of a backslash followed by any character that is not n, a backslash, or the I 

delimiter character is undefined. I 

Do nothing. This command bears a label to which the b and t commands branch. I 

Write the following to standard output: 

"%d\n", <current line number> 

Ignore this empty command. I 

Ignore the ' #' and the remainder of the line (treat them as a comment), with the I 

single exception that if the first two characters in the script are "#n", the default I 


[0addr]:label 

[laddr]= 

[Oaddr] 

[Oaddr]# 
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output shall be suppressed; this shall be the equivalent of specifying -n on the I 
command line. 


EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Regular expressions match entire strings, not just individual lines, but a <newline> character is 
matched by ' \n' in a sed RE; a <newline> character is not allowed in an RE. Also note that ' \n' 
cannot be used to match a <newline> character at the end of an arbitrary input line; <newline> 
characters appear in the pattern space as a result of the N editing command. 

EXAMPLES 

This sed script simulates the BSD cat -s command, squeezing excess blank lines from standard 
input. 

sed —n ' 

# Write non-empty lines. 

/./ { 

P 

d 

1 

# Write a single empty line, then look for more empty lines. 

/~$/ p 

# Get next line, discard the held <newline> (empty line), 

# and look for more empty lines. 

:Empty 

/-$/ { 

N 

s/.// 
b Empty 
1 

# Write the non-empty line before going back to search 

# for the first in a set of empty lines. 

P 

r 

RATIONALE 

This volume of IEEE Std. 1003.1-200x requires implementations to support at least ten distinct I 
ivfile s, matching historical practice on many implementations. Implementations are encouraged I 
to support more, but portable applications should not exceed this limit. 

The exit status codes specified here are different from those in System V. System V returns 2 for 
garbled sed commands, but returns zero with its usage message or if the input file could not be 
opened. The standard developers considered this to be a bug. 

The manner in which the 1 command writes non-printable characters was changed to avoid the 
historical backspace-overstrike method, and other requirements to achieve unambiguous output 
were added. See the RATIONALE for ed on page 369 for details of the format chosen, which is 
the same as that chosen for sed. 
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This volume of IEEE Std. 1003.1-200x requires implementations to provide pattern and hold 
spaces of at least 8192 bytes, larger than the 4000 bytes spaces used by some historical 
implementations, but less than the 20 480 bytes limit used in an early proposal. Implementations 
are encouraged to allocate dynamically larger pattern and hold spaces as needed. 

The requirements for acceptance of <blank>s and <space>s in command lines has been made 
more explicit than in early proposals to describe clearly the historical practice and to remove 
confusion about the phrase "protect initial blanks [sic] and tabs from the stripping that is done 
on every script line" that appears in much of the historical documentation of the sed utility 
description of text. (Not all implementations are known to have stripped <blank>s from text 
lines, although they all have allowed leading <blank>s preceding the address on a command 
line.) 

The treatment of ' #' comments differs from the SVID which only allows a comment as the first 
line of the script, but matches BSD-derived implementations. The comment character is treated 
as a command, and it has the same properties in terms of being accepted with leading <blank>s; 
the BSD implementation has historically supported this. 

Early proposals required that a script_file have at least one non-comment line. Some historical 
implementations have behaved in unexpected ways if this were not the case. The standard 
developers considered that this was incorrect behavior and that application developers should 
not have to avoid this feature. A correct implementation of this volume of IEEE Std. 1003.1-200x 
shall permit script Jiles that consist only of comment lines. 

Early proposals indicated that if -e and -f options were intermixed, all -e options were 
processed before any -f options. This has been changed to process them in the order presented 
because it matches historical practice and is more intuitive. 

The treatment of the p flag to the s command differs between System V and BSD-based systems 
when the default output is suppressed. In the two examples: 

echo a | sed 's/a/A/p' 
echo a I sed —n 's/a/A/p' 

This volume of IEEE Std. 1003.1-200x, BSD, System V documentation, and the SVID indicate that 
the first example should write two lines with A, whereas the second should write one. Some 
System V systems write the A only once in both examples because the p flag is ignored if the -n 
option is not specified. 

This is a case of a diametrical difference between systems that could not be reconciled through 
the compromise of declaring the behavior to be unspecified. The SVID/BSD/System V 
documentation behavior was adopted for this volume of IEEE Std. 1003.1-200x because: 

• No known documentation for any historic system describes the interaction between the p 
flag and the -n option. 

• The selected behavior is more correct as there is no technical justification for any interaction 
between the p flag and the -n option. A relationship between -n and the p flag might imply 
that they are only used together, but this ignores valid scripts that interrupt the cyclical 
nature of the processing through the use of the D, d, q, or branching commands. Such scripts 
rely on the p suffix to write the pattern space because they do not make use of the default 
output at the "bottom" of the script. 

• Because the -n option makes the p flag unnecessary, any interaction would only be useful if 
sed scripts were written to run both with and without the -n option. This is believed to be 
unlikely. It is even more unlikely that programmers have coded the p flag expecting it to be 
unnecessary. Because the interaction was not documented, the likelihood of a programmer 
discovering the interaction and depending on it is further decreased. 
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33948 • Finally, scripts that break under the specified behavior produce too much output instead of 

33949 too little, which is easier to diagnose and correct. 

33950 The form of the substitute command that uses the n suffix was limited to the first 512 matches in 

33951 an early proposal. This limit has been removed because there is no reason an editor processing 

33952 lines of |LINE_MAX} length should have this restriction. The command s/a/A/2047 should be 

33953 able to substitute the 2 047th occurrence of a on a line. 

33954 The b, t, and : commands are documented to ignore leading white space, but no mention is 

33955 made of trailing white space. Historical implementations of sed assigned different locations to 

33956 the labels ' x ' and " x " . This is not useful, and leads to subtle programming errors, but it is 

33957 historical practice, and changing it could theoretically break working scripts. Implementors are 

33958 encouraged to provide warning messages about labels that are never used or jumps to labels 

33959 that do not exist. 

33960 Historically, the sed ! and } editing commands did not permit multiple commands on a single 

33961 line using a semicolon as a command delimiter. Implementations are permitted, but not 

33962 required, to support this extension. 

33963 FUTURE DIRECTIONS 

33964 None. 

33965 SEE ALSO 

33966 azvk,ed,grep 

33967 CHANGE HISTORY 

33968 First released in Issue 2. 

33969 Issue 4 

33970 Aligned with the ISO/IEC 9945-2:1993 standard. 

33971 Issue 5 

33972 FUTURE DIRECTIONS section added. 

33973 Issue 6 

33974 The following new requirements on POSIX implementations derive from alignment with the 

33975 Single UNIX Specification: 

33976 • Implementations are required to support at least ten zvfile arguments in an editing command. 

33977 The EXTENDED DESCRIPTION is changed to align with the IEEE P1003.2b draft standard. 
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33978 NAME 

33979 sh — shell, the standard command language interpreter 

33980 SYNOPSIS 

33981 man sh [— abCefhimnuvx] [—o option] [+abCefhmnuvx] [+o option] 

33982 [ command_file [argument. . . ] ] 

33983 MAN sh —c [—abCefhimnuvx] [—o option] [+abCefhimnuvx] [+o option] command_string 

33984 [command_name [argument. . . ] ] 

33985 MAN sh —s[—abCefhimnuvx] [—o option] [+abCefhimnuvx] [+o option] [argument] 

33986 DESCRIPTION 

33987 The sh utility is a command language interpreter that shall execute commands read from a I 

33988 command line string, the standard input, or a specified file. The application shall ensure that the I 

33989 commands to be executed are expressed in the language described in Chapter 2 on page 35. I 

33990 man Path name expansion does not fail due to the size of a file. 

33991 Shell input and output redirections have an implementation-dependent offset maximum that is 

33992 established in the open file description. 

33993 OPTIONS 

33994 The sh utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

33995 Section 12.2, Utility Syntax Guidelines. I 

33996 The -a, -b, -C, -e, -f, -m, -n, -o option , -u, -v, and -x options are described as part of the set 

33997 man utility in Section 2.14 on page 96. The option letters derived from the set special built-in shall 

33998 also be accepted with a leading plus sign (' +') instead of a leading hyphen (meaning the reverse 

33999 case of the option as described in this volume of IEEE Std. 1003.1-200x). 

34000 The following additional options shall be supported: 

34001 -c Read commands from the command_string operand. Set the value of special 

34002 parameter 0 (see Section 2.5.2 on page 43) from the value of the command_name 

34003 operand and the positional parameters ($1, $2, and so on) in sequence from the 

34004 remaining argument operands. No commands shall be read from the standard 

34005 input. 

34006 -i Specify that the shell is interactive; see below. An implementation may treat 

34007 specifying the -i option as an error if the real user ID of the calling process does 

34008 not equal the effective user ID or if the real group ID does not equal the effective 

34009 group ID. 

34010 -s Read commands from the standard input. 

34011 If there are no operands and the -c option is not specified, the -s option shall be assumed. 

34012 If the -i option is present, or if there are no operands and the shell's standard input and standard 

34013 error are attached to a terminal, the shell is considered to be interactive. 

34014 OPERANDS 

34015 The following operands shall be supported: 

34016 - A single hyphen is treated as the first operand and then ignored. If both ' -' and 

34017 "—" are given as arguments, or if other operands precede the single hyphen, the 

34018 results are undefined. 

34019 argument The positional parameters ($1, $2, and so on) shall be set to arguments, if any. 
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commandjile The path name of a file containing commands. If the path name contains one or 
more slash characters, the implementation attempts to read that file; the file need 
not be executable. If the path name does not contain a slash character: 

• The implementation shall attempt to read that file from the current working 
directory; the file need not be executable. 

• If the file is not in the current working directory, the implementation may 
perform a search for an executable file using the value of PATH , as described in 
Section 2.9.1.1 on page 69. 

Special parameter 0 (see Section 2.5.2 on page 43) shall be set to the value of 
command Jile. If sh is called using a synopsis form that omits command Jile, special 
parameter 0 shall be set to the value of the first argument passed to sh from its 
parent (for example, argv[ 0] for a C program), which is normally a path name used 
to execute the sh utility. 

command_name 

A string assigned to special parameter 0 when executing the commands in 
command_string . If command_name is not specified, special parameter 0 shall be set 
to the value of the first argument passed to sh from its parent (for example, argv[ 0] 
for a C program), which is normally a path name used to execute the sh utility. 

command_string 

A string that shall be interpreted by the shell as one or more commands, as if the 
string were the argument to the system () function defined in the System Interfaces 
volume of IEEE Std. 1003.1-200x. If the command_string operand is an empty string, 
sh shall exit with a zero exit status. 


STDIN 

The standard input shall be used only if one of the following is true: 

• The -s option is specified. 

• The -c option is not specified and no operands are specified. 

• The script executes one or more commands that require input from standard input (such as a 
read command that does not redirect its input). 

See the INPUT FILES section. 

When the shell is using standard input and it invokes a command that also uses standard input, 
the shell shall ensure that the standard input file pointer points directly after the command it has 
read when the command begins execution. It shall not read ahead in such a manner that any 
characters intended to be read by the invoked command are consumed by the shell (whether 
interpreted by the shell or not) or that characters that are not read by the invoked command are 
not seen by the shell. When the command expecting to read standard input is started 
asynchronously by an interactive shell, it is unspecified whether characters are read by the 
command or interpreted by the shell. 

If the standard input to sh is a FIFO or terminal device and is set to non-blocking reads, then sh 
shall enable blocking reads on standard input. This shall remain in effect when the command 
completes. 

INPUT FILES 

The input file shall be a text file, except that line lengths shall be unlimited. If the input file is 
empty or consists solely of blank lines or comments, or both, sh shall exit with a zero exit status. 
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ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of sh: 


ENV 


FCEDIT 


HISTFILE 


HISTSIZE 


HOME 


This variable, when and only when an interactive shell is invoked, shall be I 
subjected to parameter expansion (see Section 2.6.2 on page 51) by the shell, and I 
the resulting value shall be used as a path name of a file containing shell I 
commands to execute in the current environment. The file need not be executable. I 
If the expanded value of ENV is not an absolute path name, the results are I 
unspecified. ENV shall be ignored if the real and effective user IDs or real and I 
effective group IDs of the user are different. I 

This variable, when expanded by the shell, determines the default value for the -e 
editor option's editor option-argument. If FCEDIT is null or unset, ed shall be used 
as the editor. This volume of IEEE Std. 1003.1-200x specifies the effects of this 
variable only for systems supporting the User Portability Utilities option. 

Determine a path name naming a command history file. If the HISTFILE variable is 
not set, the shell may attempt to access or create a file .sh_history in the directory 
referred to by the HOME environment variable. If the shell cannot obtain both read 
and write access to, or create, the history file, it shall use an unspecified 
mechanism that allows the history to operate properly. (References to history 
"file” in this section shall be understood to mean this unspecified mechanism in 
such cases.) An implementation may choose to access this variable only when 
initializing the history file; this initialization shall occur when fc or sh first attempt 
to retrieve entries from, or add entries to, the file, as the result of commands issued 
by the user, the file named by the ENV variable, or implementation-dependent I 
system start-up files. (The initialization process for the history file can be I 
dependent on the system start-up files, in that they may contain commands that I 
effectively preempt the user's settings of HISTFILE and HISTSIZE. For example, 
function definition commands are recorded in the history file, unless the set -o 
nolog option is set. If the system administrator includes function definitions in I 
some system start-up file called before the ENV file, the history file is initialized I 
before the user gets a chance to influence its characteristics.) In some historical 
shells, the history file is initialized just after the ENV file has been processed. 
Therefore, it is implementation-dependent whether changes made to HISTFILE 
after the history file has been initialized are effective. Implementations may 
choose to disable the history list mechanism for users with appropriate privileges 
who do not set HISTFILE ; the specific circumstances under which this occurs are 
implementation-dependent. If more than one instance of the shell is using the 
same history file, it is unspecified how updates to the history file from those shells 
interact. As entries are deleted from the history file, they shall be deleted oldest 
first. It is unspecified when history file entries are physically removed from the 
history file. This volume of IEEE Std. 1003.1-200x specifies the effects of this 
variable only for systems supporting the User Portability Utilities option. 

Determine a decimal number representing the limit to the number of previous 
commands that are accessible. If this variable is unset, an unspecified default 
greater than or equal to 128 shall be used. The maximum number of commands in 
the history list is unspecified, but shall be at least 128. An implementation may 
choose to access this variable only when initializing the history file, as described 
under HISTFILE. Therefore, it is unspecified whether changes made to HISTSIZE 
after the history file has been initialized are effective. 

Determine the path name of the user's home directory. The contents of HOME are 
used in Tilde Expansion as described in Section 2.6.1 on page 50. This volume of 
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34114 

34115 


IEEE Std. 1003.1-200x specifies the effects of this variable only for systems 
supporting the User Portability Utilities option. 

34116 

34117 

34118 

34119 

34120 

34121 

IFS 

Input field separators: a string treated as a list of characters that shall be used for 
field splitting and to split lines into words with the read command. See Section 
2.6.5 on page 58. If IFS is not set, the shell shall behave as if the value of IFS were 
the <space>, <tab>, and <newline> characters. Implementations may ignore the 
value of IFS in the environment at the time sh is invoked, treating IFS as if it were 
not set. 

34122 

34123 

34124 

34125 

34126 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

34127 

34128 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

34129 

34130 

34131 

LC_COLLATE 

Determine the behavior of range expressions, equivalence classes and multi¬ 
character collating elements within pattern matching. 

34132 

34133 

34134 

34135 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), which characters are defined as letters (character class 
alpha), and the behavior of character classes within pattern matching. 

34136 

34137 

34138 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

34139 

34140 

34141 

34142 

34143 

34144 

34145 

34146 

34147 

MAIL 

Determine a path name of the user's mailbox file for purposes of incoming mail 
notification. If this variable is set, the shell shall inform the user if the file named by 
the variable is created or if its modification time has changed. Informing the user 
shall be accomplished by writing a string of unspecified format to standard error 
prior to the writing of the next primary prompt string after the completion of an 
interval defined by the MAILCHECK variable. The user shall be informed only if 
MLAIL is set and MAILPATH is not set. This volume of IEEE Std. 1003.1-200x 
specifies the effects of this variable only for systems supporting the User 
Portability Utilities option. 

34148 

34149 

34150 

34151 

34152 

34153 

34154 

MAILCHECK 

Establish a decimal integer value that specifies how often (in seconds) the shell 
shall check for the arrival of mail in the files specified by the MAILPATH or MAIL 
variables. The default value shall be 600 seconds. If set to zero, the shell shall check 
before issuing each primary prompt. This volume of IEEE Std. 1003.1-200x 
specifies the effects of this variable only for systems supporting the User 
Portability Utilities option. 

34155 

34156 

34157 

34158 

34159 

34160 

34161 

MAILPATH 

Provide a list of path names and optional messages separated by colons. If this 
variable is set, the shell shall inform the user if any of the files named by the 
variable are created or if any of their modification times change. (See the preceding 
entry for MLAIL for descriptions of mail arrival and user informing.) Each path 
name can be followed by ' %' and a string that shall be subjected to parameter 
expansion and written to standard error when the modification time changes. If a 
' %' character in the path name is preceded by a backslash, it shall be treated as a 
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34162 

34163 

34164 

34165 

34166 

34167 

34168 

34169 

34170 

34171 

34172 

34173 

34174 

34175 

34176 

34177 

34178 

34179 

34180 

34181 

34182 

34183 

34184 

34185 

34186 

34187 

34188 

34189 

34190 

34191 

34192 

34193 

34194 

34195 

34196 

34197 

34198 

34199 

34200 

34201 

34202 

34203 

34204 


sh 


Utilities 


literal ' %' in the path name. The default message is unspecified. 

The MA1LPATH environment variable takes precedence over the MAIL variable. 
This volume of IEEE Std. 1003.1-200x specifies the effects of this variable only for 
systems supporting the User Portability Utilities option. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Establish a string formatted as described in the System Interface Definitions 

volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables, used to effect 
command interpretation; see Section 2.9.1.1 on page 69. 

PWD This variable shall represent an absolute path name of the current working 

directory. Assignments to this variable may be ignored unless the value is an 
absolute path name of the current working directory and there are no file name 
components of dot or dot-dot. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

See the STDERR section. 

STDERR 

Except as otherwise stated (by the descriptions of any invoked utilities or in interactive mode), 
standard error is used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

See Chapter 2. The following additional capabilities are supported on systems supporting the 
User Portability Utilities option. 

Command History List 

When the sh utility is being used interactively, it shall maintain a list of commands previously 
entered from the terminal in the file named by the HISTFILE environment variable. The type, 
size, and internal format of this file are unspecified. Multiple sh processes can share access to the 
file for a user, if file access permissions allow this; see the description of the HISTFILE 
environment variable. 

Command Line Editing 

When sh is being used interactively from a terminal, the current command and the command 
history (see fc on page 470) can be edited using zu-mode command line editing. This mode uses 
commands, described below, similar to a subset of those described in the vi utility. 
Implementations may offer other command line editing modes corresponding to other editing 
utilities. 

The command set -o vi shall enable A-mode editing and place sh into vi insert mode (see 
Command Line Editing (vi-mode) on page 893). This command also shall disable any other 
editing mode that the implementation may provide. The command set +o vi disables ci-mode 
editing. 

Certain block-mode terminals may be unable to support shell command line editing. If a 
terminal is unable to provide either edit mode, it need not be possible to set -o vi when using the 
shell on this terminal. 
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34205 

34206 

34207 

34208 

34209 

34210 

34211 

34212 

34213 

34214 

34215 

34216 

34217 

34218 

34219 

34220 

34221 

34222 

34223 

34224 

34225 

34226 

34227 

34228 

34229 

34230 

34231 

34232 

34233 

34234 

34235 

34236 

34237 

34238 

34239 

34240 

34241 

34242 

34243 

34244 

34245 

34246 
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In the following sections, the characters erase, interrupt, kill, and end-of-file are those set by the 
stty utility. 

Command Line Editing (vi-mode) 

With pz'-mode enabled, sh can be switched between insert mode and command mode. 

When in insert mode, an entered character shall be inserted into the command line, except as 
noted in vi Line Editing Insert Mode. Upon entering sh and after termination of the previous 
command, sh shall be in insert mode. 

Typing an escape character shall switch sh into command mode (see vi Line Editing Command 
Mode on page 894). In command mode, an entered character shall either invoke a defined 
operation, is used as part of a multi-character operation, or is treated as an error. A character that 
is not recognized as part of an editing command shall terminate any specific editing command 
and shall alert the terminal. Typing the interrupt character in command mode shall cause sh to 
terminate command line editing on the current command line, reissue the prompt on the next 
line of the terminal, and reset the command history (see/c on page 470) so that the most recently 
executed command is the previous command (that is, the command that was being edited when 
it was interrupted is not reentered into the history). 

In the following sections, the phrase "move the cursor to the beginning of the word" shall mean 
"move the cursor to the first character of the current word" and the phrase "move the cursor to 
the end of the word" shall mean "move the cursor to the last character of the current word". The 
phrase "beginning of the command line" indicates the point between the end of the prompt 
string issued by the shell (or the beginning of the terminal line, if there is no prompt string) and 
the first character of the command text. 


vi Line Editing Insert Mode 

While in insert mode, any character typed shall be inserted in the current command line, unless 
it is from the following set. 

<newline> Execute the current command line being edited. 

Delete the character previous to the current cursor position and move the current 
cursor position back one character. In insert mode, characters shall be erased from 
both the screen and the buffer when backspacing. 

Terminate command line editing with the same effects as described for 
interrupting command mode; see Command Line Editing (vi-mode). 


erase 


interrupt 


kdl 


Clear all the characters from the input line. 


<control>-V Insert the next character input, even if the character is otherwise a special insert 
mode character. 

<control>-W Delete the characters from the one preceding the cursor to the preceding word 
boundary. The word boundary in this case is the closer to the cursor of either the 
beginning of the line or a character that is in neither the blank nor punct character 
classification of the current locale. 

end-of-file Interpreted as the end of input in sh. This interpretation shall occur only at the 
beginning of an input line. If end-of-file is entered other than at the beginning of the 
line, the results are unspecified. 

<ESC> Place sh into command mode. 
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34247 vi Line Editing Command Mode 

34248 In command mode for the command line editing feature, decimal digits not beginning with 0 

34249 that precede a command letter shall be remembered. Some commands use these decimal digits 

34250 as a count number that affects the operation. 

34251 The term motion command represents one of the commands: 

34252 <space> ObFlW"$;EfTw| ,Beht 

34253 Any command that modifies the current line shall cause a copy of the current line to be made at 

34254 the end of the command history, the current line shall become that copy, and the edit is 

34255 performed on that copy. 

34256 Any command that is preceded by count shall take a count (the numeric value of any preceding 

34257 decimal digits). Unless otherwise noted, this count shall cause the specified operation to repeat 

34258 by the number of times specified by the count. Also unless otherwise noted, a count that is out of 

34259 range is considered an error condition and shall alert the terminal, but neither the cursor 

34260 position, nor the command line, shall change. 

34261 The terms word and bigzvord are used as defined in the vi description. The term save buffer 

34262 corresponds to the term unnamed buffer in vi. 

34263 The following commands shall be recognized in command mode: 

34264 <newline> Execute the current command line being edited. 

34265 <control>-L Redraw the current command line. Position the cursor at the same location on the 

34266 new command line. 


34267 # Insert the character ' #' at the beginning of the current command line and treat the 

34268 current command line as a comment. This line shall be entered into the command 

34269 history; see/c on page 470. 


34270 

34271 

34272 

34273 

34274 

34275 

34276 


Display the possible shell word expansions (see Section 2.6 on page 49) of the 
bigword at the current command line position. These expansions shall be 
displayed on subsequent terminal lines. If the bigword contains none of the 
characters ' ?', ' *', or ' [', an asterisk (' *') shall be implicitly assumed at the 
end. If any directories are matched, these expansions shall have a ' /' character 
appended. After the expansion, the line shall be redrawn, the cursor is repositioned 
at the current cursor position, and sh shall be placed in command mode. 


34277 \ Perform path name expansion (see Section 2.6.6 on page 59) on the current 

34278 bigword, up to the largest set of characters that can be matched uniquely. If the 

34279 bigword contains none of the characters or ' [', an asterisk (' *') shall 

34280 be implicitly assumed at the end. This maximal expansion then shall replace the 

34281 original bigword in the command line, and the cursor shall be placed after this 

34282 expansion. If the resulting bigword completely and uniquely matches a directory, a 

34283 ' /' character shall be inserted directly after the bigword. If some other file is 

34284 completely matched, a single <space> character shall be inserted after the bigword. 

34285 After this operation, sh shall be placed in insert mode. 


34286 * Perform path name expansion on the current bigword and insert all expansions 

34287 into the command to replace the current bigword, with each expansion separated 

34288 by a single <space> character. If at the end of the line, the current cursor position 

34289 shall be moved to the first column position following the expansions and sh shall 

34290 be placed in insert mode. Otherwise, the current cursor position shall be the last 

34291 column position of the first character after the expansions and sh shall be placed in 

34292 insert mode. If the current bigword contains none of the characters ' ?', ' *', or 
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34293 


' , before the operation, an asterisk shall be implicitly assumed at the end. 


34294 

34295 

34296 

34297 

34298 


@letter Insert the value of the alias named Jetter. The symbol letter represents a single 

alphabetic character from the portable character set; implementations may support 
additional characters as an extension. If the alias Jetter contains other editing 
commands, these commands shall be performed as part of the insertion. If no alias 
Jetter is enabled, this command shall have no effect. 


34299 

34300 

34301 

34302 

34303 

34304 

34305 

34306 

34307 


[count]' Convert, if the current character is a lowercase letter, to the equivalent uppercase 
letter and vice versa, as prescribed by the current locale. The current cursor position 
then shall be advanced by one character. If the cursor was positioned on the last 
character of the line, the case conversion shall occur, but the cursor shall not 
advance. If the ' ~' command is preceded by a count, that number of characters 
shall be converted, and the cursor shall be advanced to the character position after 
the last character converted. If the count is larger than the number of characters 
after the cursor, this shall not be considered an error; the cursor shall advance to 
the last character on the line. 


34308 

34309 

34310 

34311 

34312 

34313 

34314 


[count]. Repeat the most recent non-motion command, even if it was executed on an earlier 
command line. If the previous command was preceded by a count, and no count is 
given on the ' .' command, the count from the previous command shall be 
included as part of the repeated command. If the ' .' command is preceded by a 
count, this shall override any count argument to the previous command. The count 
specified in the ' .' command shall become the count for subsequent ' .' 
commands issued without a count. 


34315 [number]v Invoke the vi editor to edit the current command line in a temporary file. When the 

34316 editor exits, the commands in the temporary file shall be executed. If a number is 

34317 prefixed to the command, it specifies the command number in the command 

34318 history to be edited, rather than the current command line. 


34319 

34320 

34321 

34322 

34323 

34324 

34325 


[count] 1 (ell) 

[co»«f]<space> 

Move the current cursor position to the next character position. If the cursor was 
positioned on the last character of the line, the terminal shall be alerted and the 
cursor shall not be advanced. If the count is larger than the number of characters 
after the cursor, this shall not be considered an error; the cursor shall advance to 
the last character on the line. 


34326 

34327 

34328 

34329 

34330 


[count ]h Move the current cursor position to the count th (default 1) previous character 

position. If the cursor was positioned on the first character of the line, the terminal 
shall be alerted and the cursor shall not be moved. If the count is larger than the 
number of characters before the cursor, this shall not be considered an error; the 
cursor shall move to the first character on the line. 


34331 

34332 

34333 

34334 

34335 


[count] w Move to the start of the next word. If the cursor was positioned on the last 

character of the line, the terminal shall be alerted and the cursor shall not be 
advanced. If the count is larger than the number of words after the cursor, this shall 
not be considered an error; the cursor shall advance to the last character on the 
line. 


34336 

34337 

34338 

34339 

34340 


[count]\N Move to the start of the next bigword. If the cursor was positioned on the last 
character of the line, the terminal shall be alerted and the cursor shall not be 
advanced. If the count is larger than the number of bigwords after the cursor, this 
shall not be considered an error; the cursor shall advance to the last character on 
the line. 
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34341 

34342 

34343 

34344 

34345 

[count]e 

Move to the end of the current word. If at the end of a word, move to the end of the 
next word. If the cursor was positioned on the last character of the line, the 
terminal shall be alerted and the cursor shall not be advanced. If the count is larger 
than the number of words after the cursor, this shall not be considered an error; the 
cursor shall advance to the last character on the line. 

34346 

34347 

34348 

34349 

34350 

[connt]E 

Move to the end of the current bigword. If at the end of a bigword, move to the 
end of the next bigword. If the cursor was positioned on the last character of the 
line, the terminal shall be alerted and the cursor shall not be advanced. If the count 
is larger than the number of bigwords after the cursor, this shall not be considered 
an error; the cursor shall advance to the last character on the line. 

34351 

34352 

34353 

34354 

34355 

34356 

[count] b 

Move to the beginning of the current word. If at the beginning of a word, move to 
the beginning of the previous word. If the cursor was positioned on the first 
character of the line, the terminal shall be alerted and the cursor shall not be 
moved. If the count is larger than the number of words preceding the cursor, this 
shall not be considered an error; the cursor shall return to the first character on the 
line. 

34357 

34358 

34359 

34360 

34361 

34362 

[count] B 

Move to the beginning of the current bigword. If at the beginning of a bigword, 
move to the beginning of the previous bigword. If the cursor was positioned on the 
first character of the line, the terminal shall be alerted and the cursor shall not be 
moved. If the count is larger than the number of bigwords preceding the cursor, 
this shall not be considered an error; the cursor shall return to the first character on 
the line. 

34363 

34364 

A 

Move the current cursor position to the first character on the input line that is not a 
<blank> character. 

34365 

$ 

Move to the last character position on the current command line. 

34366 

0 

(Zero.) Move to the first character position on the current command line. 

34367 

34368 

34369 

34370 

34371 

[count] 1 

Move to the count th character position on the current command line. If no number 
is specified, move to the first position. The first character position shall be 
numbered 1. If the count is larger than the number of characters on the line, this 
shall not be considered an error; the cursor shall be placed on the last character on 
the line. 

34372 

34373 

34374 

34375 

34376 

[count]fc 

Move to the first occurrence of the character ' c' that occurs after the current 
cursor position. If the cursor was positioned on the last character of the line, the 
terminal shall be alerted and the cursor shall not be advanced. If the character ' c' 
does not occur in the line after the current cursor position, the terminal shall be 
alerted and the cursor shall not be moved. 

34377 

34378 

34379 

34380 

34381 

[count]Ec 

Move to the first occurrence of the character ' c' that occurs before the current 
cursor position. If the cursor was positioned on the first character of the line, the 
terminal shall be alerted and the cursor shall not be moved. If the character ' c' 
does not occur in the line before the current cursor position, the terminal shall be 
alerted and the cursor shall not be moved. 

34382 

34383 

34384 

34385 

34386 

[count]tc 

Move to the character before the first occurrence of the character ' c ' that occurs 
after the current cursor position. If the cursor was positioned on the last character 
of the line, the terminal shall be alerted and the cursor shall not be advanced. If the 
character ' c' does not occur in the line after the current cursor position, the 
terminal shall be alerted and the cursor shall not be moved. 
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34387 

34388 

34389 

34390 

34391 


[count]Tc Move to the character after the first occurrence of the character ' c' that occurs 
before the current cursor position. If the cursor was positioned on the first 
character of the line, the terminal shall be alerted and the cursor shall not be 
moved. If the character ' c' does not occur in the line before the current cursor 
position, the terminal shall be alerted and the cursor shall not be moved. 


34392 

34393 

34394 


[count]; Repeat the most recent f, F, t, or T command. Any number argument on that 
previous command shall be ignored. Errors are those described for the repeated 
command. 


34395 

[count], 

Repeat the most recent f. 

34396 


previous command shall 

34397 


command. 


F, t, or T command. Any number argument on that 
be ignored. However, reverse the direction of that 


34398 a Enter insert mode after the current cursor position. Characters that are entered 

34399 shall be inserted before the next character. 


34400 A 


Enter insert mode after the end of the current command line. 


34401 i Enter insert mode at the current cursor position. Characters that are entered are 

34402 inserted before the current character. 


34403 I 

34404 R 

34405 


Enter insert mode at the beginning of the current command line. 

Enter insert mode, replacing characters from the command line beginning at the 
current cursor position. 


34406 

34407 

34408 

34409 

34410 

34411 


[count]cmotion 

Delete the characters between the current cursor position and the cursor position 
that would result from the specified motion command. Then enter insert mode 
before the first character following any deleted characters. If count is specified, it 
shall be applied to the motion command. A count shall be ignored for the following 
motion commands: 


34412 


0 A $ C 


34413 

34414 

34415 

34416 

34417 

34418 

34419 

34420 

34421 

34422 

34423 

34424 


If the motion command is the character ' c', the current command line shall be 
cleared and insert mode shall be entered. If the motion command would move the 
current cursor position toward the beginning of the command line, the character 
under the current cursor position shall not be deleted. If the motion command 
would move the current cursor position toward the end of the command line, the 
character under the current cursor position shall be deleted. If the count is larger 
than the number of characters between the current cursor position and the end of 
the command line toward which the motion command would move the cursor, 
this shall not be considered an error; all of the remaining characters in the 
aforementioned range shall be deleted and insert mode shall be entered. If the 
motion command is invalid, the terminal shall be alerted, the cursor shall not be 
moved, and no text shall be deleted. 


34425 C Delete from the current character to the end of the line and enter insert mode at the 

34426 new end-of-line. 


34427 S 


Clear the entire current command line and enter insert mode. 


34428 

34429 

34430 

34431 

34432 


[count]rc Replace the current character with the character ' c'. With a number count, 
replace the current and the following count-1 characters. After this command, the 
current cursor position shall be on the last character that was changed. If the count 
is larger than the number of characters after the cursor, this shall not be considered 
an error; all of the remaining characters shall be changed. 
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34433 

34434 

34435 

34436 

34437 

34438 

34439 

34440 

34441 

34442 

34443 

34444 

34445 

34446 

34447 

34448 

34449 

34450 

34451 

34452 

34453 

34454 

34455 

34456 

34457 

34458 

34459 

34460 

34461 

34462 

34463 

34464 

34465 

34466 

34467 

34468 

34469 

34470 

34471 

34472 

34473 

34474 

34475 

34476 

34477 

34478 

34479 

34480 

34481 
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[connt]_ Append a <space> character after the current character position and then append 
the last bigword in the previous input line after the <space> character. Then enter 
insert mode after the last character just appended. With a number count, append 
the count th bigword in the previous line. 

[count]x Delete the character at the current cursor position and place the deleted characters 
in the save buffer. If the cursor was positioned on the last character of the line, the 
character shall be deleted and the cursor position shall be moved to the previous 
character (the new last character). If the count is larger than the number of 
characters after the cursor, this shall not be considered an error; all the characters 
from the cursor to the end of the line shall be deleted. 

[count]X Delete the character before the current cursor position and place the deleted 
characters in the save buffer. The character under the current cursor position shall 
not change. If the cursor was positioned on the first character of the line, the 
terminal shall be alerted, and the X command shall have no effect. If the line 
contained a single character, the X command shall have no effect. If the line 
contained no characters, the terminal shall be alerted and the cursor shall not be 
moved. If the count is larger than the number of characters before the cursor, this 
shall not be considered an error; all the characters from before the cursor to the 
beginning of the line shall be deleted. 

[count]dmotion 

Delete the characters between the current cursor position and the character 
position that would result from the motion command. A number count repeats the 
motion command count times. If the motion command would move toward the 
beginning of the command line, the character under the current cursor position 
shall not be deleted. If the motion command is d, the entire current command line 
shall be cleared. If the count is larger than the number of characters between the 
current cursor position and the end of the command line toward which the motion 
command would move the cursor, this shall not be considered an error; all of the 
remaining characters in the aforementioned range shall be deleted. The deleted 
characters shall be placed in the save buffer. 

D Delete all characters from the current cursor position to the end of the line. The 

deleted characters shall be placed in the save buffer. 

[count]ymotion 

Yank (that is, copy) the characters from the current cursor position to the position 
resulting from the motion command into a save buffer. A number count shall be 
applied to the motion command. If the motion command would move toward the 
beginning of the command line, the character under the current cursor position 
shall not be included in the set of yanked characters. If the motion command is y, 
the entire current command line shall be yanked into the save buffer. The current 
cursor position shall be unchanged. If the count is larger than the number of 
characters between the current cursor position and the end of the command line 
toward which the motion command would move the cursor, this shall not be 
considered an error; all of the remaining characters in the aforementioned range 
shall be yanked. 

Y Yank the characters from the current cursor position to the end of the line into the 

save buffer. The current character position shall be unchanged. 

[count ]p Put a copy of the current contents of the save buffer after the current cursor 

position. The current cursor position shall be advanced to the last character put 
from the save buffer. A count shall indicate how many copies of the save buffer 
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shall be put. 

Put a copy of the current contents of the save buffer before the current cursor 
position. The current cursor position shall be moved to the last character put from 
the save buffer. A count shall indicate how many copies of the save buffer shall be 
put. 

Undo the last command that modified the text of the current command line. 

Undo all changes made to the current command line since first entering command 
mode on the line. 

Replace the current command line with the previous command line in the shell 
command history. The cursor shall be positioned on the first character of the new 
command. A count preceding the command shall have the same effect as 
executing the command count times. If a k or - command retreats past the 
maximum number of commands in effect for this shell (affected by the HISTSIZE 
environment variable), the terminal shall be alerted and the command shall have 
no effect. 

Replace the current command line with the next command line in the shell 
command history. The cursor shall be positioned on the first character of the new 
command. The command history position shall be remembered, and any k or - 
command, or j or + command, shall decrement or increment that position and then 
shall fetch the line at the new position. If a j or + command advances past the most 
recent line in the history, the current command line shall be restored to the 
contents before the first k or -. 

[number] G Replace the current command line with the contents of the oldest command line 

stored in the shell command history. With a number number, replace the current 
command line with the contents of command number in the history. 

/sfnny<newline> 

Move backward through the command history, searching for the specified string, 
beginning with the previous command line. If it is not found, the current 
command line shall be unchanged. If it is found in a previous line, this command 
shall behave equivalently to a set of k commands to reach that line. If string begins 
with ' "', the characters after the ' '' shall be matched only at the beginning of a 
line. 

?string<new I i ne> 

Move forward through the command history, searching for the specified string. If 
it is not found, the current command line shall be unchanged. If the string is found 
in the current command line, the current cursor position shall be moved to the 
beginning of that string. If it is found in the history, this command shall behave 
equivalently to a set of j commands to reach that line. If string begins with ' "', the 
characters after the ' ' ' shall be matched only at the beginning of a line. 

n Repeat the most recent / or ? command. 

N Repeat the most recent / or ? command, reversing the direction of the search. 
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[count] P 


u 

U 

[count] k 
[count]- 


[count] j 
[count]+ 
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EXIT STATUS 

The following exit values shall be returned: 

0 The script to be executed consisted solely of zero or more blank lines or comments, or 
both. 

1-125 A non-interactive shell detected a syntax, redirection or variable assignment error. 

127 A specified command_file could not be found by a non-interactive shell. 

Otherwise, the shell shall return the exit status of the last command it invoked or attempted to 
invoke (see also the exit utility in Section 2.14 on page 96). 

CONSEQUENCES OF ERRORS 

See Section 2.8.1 on page 65. 

APPLICATION USAGE 

Standard input and standard error are the files that determine whether a shell is interactive 
when -i is not specified. For example: 

sh > file 

and: 

sh 2> file 

create interactive and non-interactive shells, respectively. Although both accept terminal input, 
the results of error conditions are different, as described in Section 2.8.1 on page 65; in the second 
example a redirection error encountered by a special built-in utility aborts the shell. 

On systems that support set-user-ID scripts, a historical trapdoor has been to link a script to the 
name -i. When it is called by a sequence such as: 

sh — 

or by: 

#! /bin/sh — 

the historical systems have assumed that no option letters follow. Thus, this volume of 
IEEE Std. 1003.1-200x allows the single hyphen to mark the end of the options, in addition to the 
use of the regular "—" argument, because the older practice is so pervasive. 

A portable application must protect its first operand, if it starts with a plus sign, by preceding it 
with the "—" argument that denotes the end of the options. 

EXAMPLES 

1. Execute a shell command from a string: 

sh —c "cat myfile" 

2. Execute a shell script from a file in the current directory: 

sh my_shell_cmds 

RATIONALE 

The sh utility and the set special built-in utility share a common set of options. 

The KomShell ignores the contents of IFS upon entry to the script. A conforming application 
cannot rely on importing IFS. One justification for this, beyond security considerations, is to 
assist possible future shell compilers. Allowing IFS to be imported from the environment 
prevents many optimizations that might otherwise be performed via dataflow analysis of the 
script itself. 
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The text in the STDIN section about non-blocking reads concerns an instance of sli that has been 
invoked, probably by a C-language program, with standard input that has been opened using 
the 0_NONBLOCK flag; see open() in the System Interfaces volume of IEEE Std. 1003.1-200x. If 
the shell did not reset this flag, it would immediately terminate because no input data would be 
available yet and that would be considered the same as end-of-file. 

The options associated with a restricted shell (command name rsh and the -r option) were 
excluded because the standard developers considered that the implied level of security could 
not be achieved and they did not want to raise false expectations. 

On systems that support set-user-ID scripts, a historical trapdoor has been to link a script to the 
name -i. When it is called by a sequence such as sh - or by #!/bin/sh -, the historical systems 
have assumed that no option letters follow. Thus, this volume of IEEE Std. 1003.1-200x allows 
the single hyphen to mark the end of the options, in addition to the use of the regular "—" 
argument, because it was considered that the older practice was so pervasive. An alternative 
approach is taken by the KornShell, where real and effective user/group IDs must match for an 
interactive shell; this behavior is specifically allowed by this volume of IEEE Std. 1003.1-200x. 

Note: There are other problems with set-user-ID scripts that the two approaches described 

here do not resolve. 

The default messages for the various MAIL -related messages are unspecified because they vary 
across implementations. Typical messages are: 

"you have mail\n" 

or: 

"you have new mail\n" 

It is important that the descriptions of command line editing refer to the same shell as that in the I 
base standard so that interactive users can also be application programmers without having to 
deal with programmatic differences in their two environments. It is also essential that the utility 
name sh be specified because this explicit utility name is too firmly rooted in historical practice 
of application programs for it to change. 

Consideration was given to mandating a diagnostic message when attempting to set pi-mode on I 
terminals that do not support command line editing. However, it is not historical practice for the I 
shell to be cognizant of all terminal types and thus be able to detect inappropriate terminals in 
all cases. Implementations are encouraged to supply diagnostics in this case whenever possible, 
rather than leaving the user in a state where editing commands work incorrectly. 

In early proposals, the KomShell-derived emacs mode of command line editing was included, I 
even though the emacs editor itself was not. The community of emacs proponents was adamant I 
that the full emacs editor not be included in this volume of IEEE Std. 1003.1-200x because they 
were concerned that an attempt to standardize this very powerful environment would 
encourage vendors to ship versions conforming strictly to this volume of IEEE Std. 1003.1-200x, 
but lacking the extensibility required by the community. The author of the original emacs 
program also expressed his desire to omit the program. Furthermore, there were a number of 
historical systems that did not include emacs, or included it without supporting it, but there were 
very few that did not include and support vi. The shell emacs command line editing mode was I 
finally omitted from this volume of IEEE Std. 1003.1-200x because it became apparent that the I 
KornShell version and the editor being distributed with the GNU system had diverged in some 
respects. The author of emacs requested that the POSIX emacs mode either be deleted or have a 
significant number of unspecified conditions. Although the KornShell author agreed to consider 
changes to bring the shell into alignment, the standard developers decided to defer specification 
at this time, rather than attempting to agree on a specific subset of emacs late within the 
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development of this volume of IEEE Std. 1003.1-200x. It is assumed that the emacs and KomShell 
developers will converge on a definition acceptable to both groups, and this may be used as a 
model for a future version of this volume of IEEE Std. 1003.1-200x. In the interim, 
implementations are free to offer additional command line editing modes based on the exact I 
models of editors their users are most comfortable with. I 

Early proposals had the following list entry in vi Line Editing Insert Mode on page 893: 

\ If followed by the erase or kill character, that character shall be inserted into the input line. 
Otherwise, the backslash itself shall be inserted into the input line. 

However, this is not actually a feature of sh command line editing insert mode, but one of some I 
historical terminal line drivers. Some conforming implementations continue to do this when the I 
stty iexten flag is set. 

FUTURE DIRECTIONS 

None. I 

SEE ALSO 

cd, echo, pzvd, test, umask, the System Interfaces volume of IEEE Std. 1003.1-200x, dup (), exec, 
exit( ),fork(), pipe (), signal (), system{), ulimit (), nmask (), wait{) 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Description of the shell command language and special built-ins moved to Chapter 2 on page 35. 

Issue 5 

FUTURE DIRECTIONS section added. 

Text is added to the DESCRIPTION for the Large File Summit proposal. 

Issue 6 

The Open Group corrigenda item U029/2 has been applied, correcting the second SYNOPSIS. 

The Open Group corrigenda item U027/3 has been applied, correcting a typographical error. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The option letters derived from the set special built-in are also accepted with a leading plus 

sig n (' + '). 

• Large file extensions are added: 

— Path name expansion does not fail due to the size of a file. 

— Shell input and output redirections have an implementation-dependent offset maximum 
that is established in the open file description. 

In the ENVIRONMENT VARIABLES section, the text "user's home directory" is updated to 
"directory referred to by the HOME environment variable". I 

Descriptions for the ENV and PWD environment variables are included to align with the I 
IEEE P1003.2b draft standard. I 

The normative text is reworded to avoid use of the term "must" for application requirements. I 
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34653 NAME 

34654 sleep — suspend execution for an interval 

34655 SYNOPSIS 

34656 sleep time 

34657 DESCRIPTION 

34658 The sleep utility shall suspend execution for at least the integral number of seconds specified by 

34659 the time operand. 

34660 OPTIONS 

34661 None. 

34662 OPERANDS 

34663 The following operand shall be supported: 

34664 time A non-negative decimal integer specifying the number of seconds for which to 

34665 suspend execution. 

34666 STDIN 

34667 Not used. 

34668 INPUT FILES 

34669 None. 


34670 ENVIRONMENT VARIABLES 

34671 The following environment variables shall affect the execution of sleep: 


34672 

34673 

34674 

34675 

34676 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


34677 

34678 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


34679 

34680 

34681 


LCJZTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


34682 LC_MESSAGES 

34683 Determine the locale that should be used to affect the format and contents of 

34684 diagnostic messages written to standard error. 

34685 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


34686 ASYNCHRONOUS EVENTS 

34687 If the sleep utility receives a SIGALRM signal, one of the following actions shall be taken: 

34688 1. Terminate normally with a zero exit status. 

34689 2. Effectively ignore the signal. 

34690 3. Provide the default behavior for signals described in the ASYNCHRONOUS EVENTS 

34691 section of Section 1.11 on page 25. This could include terminating with a non-zero exit 

34692 status. 


34693 The sleep utility shall take the standard action for all other signals. 
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34694 STDOUT 

34695 Not used. 

34696 STDERR 

34697 Used only for diagnostic messages. 

34698 OUTPUT FILES 

34699 None. 

34700 EXTENDED DESCRIPTION 

34701 None. 

34702 EXIT STATUS 

34703 The following exit values shall be returned: 

34704 0 The execution was successfully suspended for at least time seconds, or a SIGALRM signal 

34705 was received. See the ASYNCHRONOUS EVENTS section. 

34706 >0 An error occurred. 

34707 CONSEQUENCES OF ERRORS 

34708 Default. 

34709 APPLICATION USAGE 

34710 None. 

34711 EXAMPLES 

34712 The sleep utility can be used to execute a command after a certain amount of time, as in: 

34713 (sleep 105; command) & 

34714 or to execute a command every so often, as in: 

34715 while true 

34716 do 

34717 command 

34718 sleep 37 

34719 done 

34720 RATIONALE 

34721 The exit status is allowed to be zero when sleep is interrupted by the SIGALRM signal because 

34722 most implementations of this utility rely on the arrival of that signal to notify them that the 

34723 requested finishing time has been successfully attained. Such implementations thus do not 

34724 distinguish this situation from the successful completion case. Other implementations are 

34725 allowed to catch the signal and go back to sleep until the requested time expires or to provide 

34726 the normal signal termination procedures. 

34727 As with all other utilities that take integral operands and do not specify subranges of allowed 

34728 values, sleep is required by this volume of IEEE Std. 1003.1-200x to deal with time requests of up 

34729 to 2 147 483 647 seconds. This may mean that some implementations have to make multiple calls 

34730 to the delay mechanism of the underlying operating system if its argument range is less than 

34731 this. 

34732 FUTURE DIRECTIONS 

34733 None. 

34734 SEE ALSO 

34735 wait, the System Interfaces volume of IEEE Std. 1003.1-200x, alarm(), sleep() 
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34736 CHANGE HISTORY 

34737 First released in Issue 2. 

34738 Issue 4 

34739 Aligned with the ISO/IEC 9945-2:1993 standard. 
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34740 NAME 

34741 sort — sort, merge, or sequence check text files 

34742 SYNOPSIS 

34743 sort [—m] [—o output ] [— bdfinru] [—t char ] [—k keydef ] . . . [file. . .] 

34744 sort — c [—bdfinru] [—t char ] [—k keydef ] . . . [file. . .] 

34745 DESCRIPTION 

34746 The sort utility shall perform one of the following functions: 

34747 1. Sort lines of all the named files together and write the result to the specified output. 

34748 2. Merge lines of all the named (presorted) files together and write the result to the specified 

34749 output. 

34750 3. Check that a single input file is correctly presorted. 

34751 Comparisons shall be based on one or more sort keys extracted from each line of input (or the 

34752 entire line if no sort keys are specified), and shall be performed using the collating sequence of 

34753 the current locale. 


34754 OPTIONS 

34755 The sort utility shall conform to the System Interface Definitions volume of I 

34756 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, and the -k keydef option should I 

34757 follow the -b, -d, -f, -i, -n, and -r options. 

34758 The following options shall be supported: 


34759 -C 

34760 

34761 


Check that the single input file is ordered as specified by the arguments and the 
collating sequence of the current locale. No output shall be produced; only the exit 
code shall be affected. 


34762 -m 


Merge only; the input file shall be assumed to be already sorted. 


34763 

34764 


-o output Specify the name of an output file to be used instead of the standard output. This 
file can be the same as one of the input files. 


34765 -U 

34766 

34767 


Unique: suppress all but one in each set of lines having equal keys. If used with 
the -c option, check that there are no lines with duplicate keys, in addition to 
checking that the input file is sorted. 


34768 The following options shall override the default ordering rules. When ordering options appear 

34769 independent of any key field specifications, the requested field ordering rules shall be applied 

34770 globally to all sort keys. When attached to a specific key (see -k), the specified ordering options 

34771 shall override all global ordering options for that key. 


34772 

34773 

34774 


-d Specify that only <blank> characters and alphanumeric characters, according to 

the current setting of LCJCTYPE, shall be significant in comparisons. The behavior 
is undefined for a sort key to which -i or -n also applies. 


34775 -f 

34776 

34777 


Consider all lowercase characters that have uppercase equivalents, according to 
the current setting of LCJZTYPE, to be the uppercase equivalent for the purposes 
of comparison. 


34778 -i Ignore all characters that are non-printable, according to the current setting of 

34779 LCJZTYPE. 


34780 

34781 

34782 


-n Restrict the sort key to an initial numeric string, consisting of optional <blank> 

characters, optional minus sign, and zero or more digits with an optional radix 
character and thousands separators (as defined in the current locale), which shall 
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be sorted by arithmetic value. An empty digit string shall be treated as zero. 
Leading zeros and signs on zeros shall not affect ordering. 

-r Reverse the sense of comparisons. 

The treatment of field separators can be altered using the options: 

-b Ignore leading <blank> characters when determining the starting and ending 

positions of a restricted sort key. If the -b option is specified before the first -k 
option, it shall be applied to all -k options. Otherwise, the -b option can be 
attached independently to each -k field_start or field_end option-argument (see 
below). 

-t char Use char as the field separator character; char shall not be considered to be part of a 

field (although it can be included in a sort key). Each occurrence of char shall be 
significant (for example, <charxchar> delimits an empty field). If -t is not 
specified, <blank> characters shall be used as default field separators; each 
maximal non-empty sequence of <blank> characters that follows a non-<blank> 
character shall be a field separator. 

Sort keys can be specified using the options: 

-k keydef The keydef argument is a restricted sort key field definition. The format of this 
definition is: 

field_start [type] [, field_end[type ]] 

where field_start and field_end define a key field restricted to a portion of the line 
(see the EXTENDED DESCRIPTION section), and type is a modifier from the list of 
characters ' b', ' d', ' f' , ' i' , ' n', ' r' . The ' b' modifier shall behave like the 
-b option, but applies only to the field_start or field_end to which it is attached. The 
other modifiers shall behave like the corresponding options, but shall apply only 
to the key field to which they are attached; they shall have this effect if specified 
with field_start, field_end, or both. If any modifier is attached to a field_start or to a 
field_end, no option shall apply to either. Implementations shall support at least 
nine occurrences of the -k option, which shall be significant in command line 
order. If no -k option is specified, a default sort key of the entire line shall be used. 

When there are multiple key fields, later keys shall be compared only after all 
earlier keys compare equal. Except when the -u option is specified, lines that 
otherwise compare equal shall be ordered as if none of the options -d, -f, -i, -n, or 
-k were present (but with -r still in effect, if it was specified) and with all bytes in 
the lines significant to the comparison. The order in which lines that still compare 
equal are written is unspecified. 

OPERANDS 

The following operand shall be supported: 

file A path name of a file to be sorted, merged, or checked. If no file operands are 

specified, or if a file operand is ' - ', the standard input shall be used. 

STDIN 

The standard input shall be used only if no file operands are specified, or if a file operand is ' . 

See the INPUT FILES section. 
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34825 INPUT FILES 

34826 The input files shall be text files, except that the sort utility shall add a <newline> character to I 

34827 the end of a file ending with an incomplete last line. 


34828 ENVIRONMENT VARIABLES 

34829 The following environment variables shall affect the execution of sort: 


34830 

34831 

34832 

34833 

34834 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


34835 

34836 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


34837 LCjCOLLATE 

34838 Determine the locale for ordering rules. 

34839 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

34840 characters (for example, single-byte as opposed to multi-byte characters in 

34841 arguments and input files) and the behavior of character classification for the -b, 

34842 -d, -f, -i, and -n options. 

34843 LC_MESSAGES 

34844 Determine the locale that should be used to affect the format and contents of 

34845 diagnostic messages written to standard error. 

34846 LC_NUMERIC 

34847 Determine the locale for the definition of the radix character and thousands 

34848 separator for the -n option. 

34849 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

34850 ASYNCHRONOUS EVENTS 

34851 Default. 


34852 STDOUT 

34853 Unless the -o or -c options are in effect, the standard output shall contain the sorted input. 

34854 STDERR 

34855 Used for diagnostic messages. A warning message about correcting an incomplete last line of an 

34856 input file may be generated, but need not affect the final exit status. 

34857 OUTPUT FILES 

34858 If the -o option is in effect, the sorted input shall be placed in the file output. 

34859 EXTENDED DESCRIPTION 

34860 The notation: 

34861 —k field_start [type] [, field_end[type] ] 

34862 shall define a key field that begins at field_start and ends at field_end inclusive, unless field_start 

34863 falls beyond the end of the line or after field_end, in which case the key field is empty. A missing 

34864 field_end shall mean the last character of the line. 

34865 A field comprises a maximal sequence of non-separating characters and, in the absence of option 

34866 -t, any preceding field separator. 

34867 Th efield_start portion of the keydef option-argument shall have the form: 
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34868 

34869 

34870 

34871 

34872 

34873 

34874 

34875 

34876 

34877 

34878 

34879 

34880 

34881 

34882 

34883 

34884 

34885 

34886 

34887 

34888 

34889 

34890 

34891 

34892 

34893 

34894 

34895 

34896 

34897 

34898 

34899 

34900 

34901 

34902 

34903 

34904 

34905 

34906 

34907 

34908 

34909 


field_number[.first_character ] 

Fields and characters within fields shall be numbered starting with 1. Th e field_number and 
first_character pieces, interpreted as positive decimal integers, shall specify the first character to 
be used as part of a sort key. If first-Character is omitted, it shall refer to the first character of the 
field. 

Th efield_end portion of the keydef option-argument shall have the form: 

field_number[.last_character] 

The field_niimber shall be as described above for field_start. The last_character piece, interpreted 
as a non-negative decimal integer, shall specify the last character to be used as part of the sort 
key. If last-Character evaluates to zero or .last-Character is omitted, it shall refer to the last 
character of the field specified by field_nnmber. 

If the -b option or b type modifier is in effect, characters within a field shall be counted from the 
first non-<blank> character in the field. (This shall apply separately to first_clmracter and 
last_character.) 

EXIT STATUS 

The following exit values shall be returned: 

0 All input files were output successfully, or -c was specified and the input file was correctly 
sorted. 

1 Under the -c option, the file was not ordered as specified, or if the -c and -u options were 
both specified, two input lines were found with equal keys. 

>1 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The default value for -t, <blank> character, has different properties from, for example, -t 
"<space>. If a line contains: 

<space><space>foo 

the following treatment would occur with default separation as opposed to specifically selecting 
a <space> character: 


Field 

Default 

-t"<space>" 

1 

<spacexspace>foo 

empty 

2 

empty 

empty 

3 

empty 

too 


The leading field separator itself is included in a field when -t is not used. For example, this 
command returns an exit status of zero, meaning the input was already sorted: 

sort —c —k 2 «eof 

y<tab>b 

x<space>a 

eof 

(assuming that a <tab> character precedes the <space> character in the current collating 
sequence). The field separator is not included in a field when it is explicitly set via -t. This is 
historical practice and allows usage such as: 


Commands and Utilities, Issue 6 


909 




34910 

34911 

34912 

34913 

34914 

34915 

34916 

34917 

34918 

34919 

34920 

34921 

34922 

34923 

34924 

34925 

34926 

34927 

34928 

34929 

34930 

34931 

34932 

34933 

34934 

34935 

34936 

34937 

34938 

34939 

34940 

34941 

34942 

34943 

34944 

34945 

34946 

34947 

34948 

34949 

34950 

34951 

34952 


sort Utilities 


sort —t " | " — k 2n «eof 
Atlanta|425022|Georgia 
Birmingham|284413|Alabama 
Columbia|100385|South Carolina 
eof 

where the second field can be correctly sorted numerically without regard to the non-numeric 
field separator. 

The wording in the OPTIONS section clarifies that the -b, -d, -f, -i, -n, and -r options have to 
come before the first sort key specified if they are intended to apply to all specified keys. The 
way it is described in this volume of IEEE Std. 1003.1-200x matches historical practice, not 
historical documentation. In the non-obsolescent versions, the results are unspecified if these 
options are specified after a -k option. 

The -f option might not work as expected in locales where there is not a one-to-one mapping 
between an uppercase and a lowercase letter. 

EXAMPLES 

1. The following command sorts the contents of infile with the second field as the sort key: 

sort —k 2,2 infile 

2. The following command sorts, in reverse order, the contents of infilel and infile2, placing 
the output in outfile and using the second character of the second field as the sort key 
(assuming that the first character of the second field is the field separator): 

sort —r —o outfile —k 2.2,2.2 infilel infile2 

3. The following command sorts the contents of infilel and infile2 using the second non- 
<blank> character of the second field as the sort key: 

sort —k 2.2b,2.2b infilel infile2 

4. The following command prints the System V password file (user database) sorted by the 
numeric user ID (the third colon-separated field): 

sort —t : —k 3,3n /etc/passwd 

5. The following command prints the lines of the already sorted file infile, suppressing all 
but one occurrence of lines having the same third field: 

sort —urn —k 3.1,3.0 infile 

RATIONALE 

Examples in some historical documentation state that options -um with one input file keep the 
first in each set of lines with equal keys. This behavior was deemed to be an implementation 
artifact and was not standardized. 

The -z option was omitted; it is not standard practice on most systems and is inconsistent with 
using sort to sort several files individually and then merge them together. The text concerning -z 
in historical documentation appeared to require implementations to determine the proper buffer 
length during the sort phase of operation, but not during the merge. 

The -y option was omitted because of non-portability. The -M option, present in System V, was 
omitted because of non-portability in international usage. 

An undocumented -T option exists in some implementations. It is used to specify a directory for 
intermediate files. Implementations are encouraged to support the use of the TMPDIR 
environment variable instead of adding an option to support this functionality. 
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34953 The -k option was added to satisfy two objections. First, the zero-based counting used by sort is 

34954 not consistent with other utility conventions. Second, it did not meet syntax guideline 

34955 requirements. 

34956 Historical documentation indicates that "setting -n implies -b". The description of -n already 

34957 states that optional leading <blank>s are tolerated in doing the comparison. If -b is enabled, 

34958 rather than implied, by -n, this has unusual side effects. When a character offset is used in a 

34959 column of numbers (for example, to sort modulo 100), that offset is measured relative to the 

34960 most significant digit, not to the column. Based upon a recommendation from the author of the 

34961 original sort utility, the -b implication has been omitted from this volume of 

34962 IEEE Std. 1003.1-200x, and an application wishing to achieve the previously mentioned side 

34963 effects has to code the -b flag manually. 

34964 FUTURE DIRECTIONS 

34965 None. 

34966 SEE ALSO 

34967 comm, join, uniq, the System Interfaces volume of IEEE Std. 1003.1-200x, tonpper () 

34968 CHANGE HISTORY 

34969 First released in Issue 2. 

34970 Issue 4 

34971 Aligned with the ISO/IEC 9945-2:1993 standard. 


Commands and Utilities, Issue 6 


911 



Utilities 


34972 

34973 

34974 

34975 

34976 

34977 

34978 

34979 

34980 

34981 

34982 

34983 

34984 

34985 

34986 

34987 

34988 

34989 

34990 

34991 

34992 

34993 

34994 

34995 

34996 

34997 

34998 

34999 

35000 

35001 

35002 

35003 

35004 

35005 

35006 

35007 

35008 

35009 

35010 

35011 

35012 

35013 

35014 

35015 

35016 


split 


NAME 

split — split files into pieces 

SYNOPSIS 

UP split [—1 line_count ] [—a suffix_length ][ file[name ]] 

split — b n[k|m][—a suffix_length ][ file[name ]] 


DESCRIPTION 

The split utility shall read an input file and write one or more output files. The default size of 
each output file shall be 1000 lines. The size of the output files can be modified by specification 
of the -b or -1 options. Each output file shall be created with a unique suffix. The suffix shall 
consist of exactly suffix_length lowercase letters from the POSIX locale. The letters of the suffix 
shall be used as if they were a base-26 digit system, with the first suffix to be created consisting 
of all ' a' characters, the second with a ' b' replacing the last ' a', and so on, until a name of all 
' z' characters is created. By default, the names of the output files shall be ' x' , followed by a 
two-character suffix from the character set as described above, starting with "aa", "ab", "ac", 
and so on, and continuing until the suffix " z z ", for a maximum of 676 files. 

If the number of files required exceeds the maximum allowed by the suffix length provided, 
such that the last allowable file would be larger than the requested size, the split utility shall fail 
after creating the last file with a valid suffix; split shall not delete the files it created with valid 
suffixes. If the file limit is not exceeded, the last file created shall contain the remainder of the 
input file, and may be smaller than the requested size. 

OPTIONS 

The split utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-a suffixjength 

Use suffixjength letters to form the suffix portion of the file names of the split file. 

If -a is not specified, the default suffix length shall be two. If the sum of the name 
operand and the suffixjength option-argument would create a file name exceeding 
|NAME_MAX} bytes, an error shall result; split shall exit with a diagnostic 
message and no files shall be created. 

-b n Split a file into pieces n bytes in size. 

-b nk Split a file into pieces n* 1024 bytes in size. 

-b ran Split a file into pieces n * 1048 576 bytes in size. 

-1 line_count Specify the number of lines in each resulting file piece. The line_count argument is 
an unsigned decimal integer. The default is 1000. If the input does not end with a 
<newline> character, the partial line shall be included in the last output file. 

OPERANDS 

The following operands shall be supported: 

file The path name of the ordinary file to be split. If no input file is given or file is ' , 

the standard input shall be used. 

name The prefix to be used for each of the files resulting from the split operation. If no 

name argument is given, ' x' shall be used as the prefix of the output files. The 
combined length of the basename of prefix and suffixjength cannot exceed 
|NAME_MAX} bytes. See the OPTIONS section. 
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35017 STDIN 

35018 See the INPUT FILES section. 


35019 INPUT FILES 

35020 Any file can be used as input. 


35021 ENVIRONMENT VARIABLES 

35022 The following environment variables shall affect the execution of split: 


35023 

35024 

35025 

35026 

35027 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


35028 

35029 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


35030 

35031 

35032 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


35033 LC_MESSAGES 

35034 Determine the locale that should be used to affect the format and contents of 

35035 diagnostic messages written to standard error. 

35036 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


35037 ASYNCHRONOUS EVENTS 

35038 Default. 


35039 STDOUT 

35040 Not used. 


35041 STDERR 

35042 Used only for diagnostic messages. 

35043 OUTPUT FILES 

35044 The output files contain portions of the original input file; otherwise, unchanged. 

35045 EXTENDED DESCRIPTION 

35046 None. 


35047 EXIT STATUS 

35048 The following exit values shall be returned: 

35049 0 Successful completion. 

35050 >0 An error occurred. 


35051 CONSEQUENCES OF ERRORS 

35052 Default. 
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35053 APPLICATION USAGE 

35054 Application writers should note that this utility need not be provided on systems that do not 

35055 support the User Portability Utilities option. 

35056 EXAMPLES 

35057 In the following examples foo is a text file that contains 5 000 lines. 

35058 1. Create five files, xaa, xab, xac, xad, and xae: 

35059 split foo 

35060 2. Create five files, but the suffixed portion of the created files consists of three letters, xaaa, 

35061 xaab, xaac, xaad, and xaae: 

35062 split —a 3 foo 

35063 3. Create three files with four-letter suffixes and a supplied prefix, bar_aaaa, bar_aaab, and 

35064 bar_aaac: 

35065 split —a 4 —1 2000 foo bar_ 

35066 4. Create as many files as are necessary to contain at most 20*1 024 bytes, each with the 

35067 default prefix of x and a five-letter suffix: 

35068 split —a 5 —b 2 0k foo 

35069 RATIONALE 

35070 The -b option was added to provide a mechanism for splitting files other than by lines. While 

35071 most uses of the -b option are for transmitting files over networks, some believed it would have 

35072 additional uses. 

35073 The -a option was added to overcome the limitation of being able to create only 676 files. 

35074 Consideration was given to deleting this utility, using the rationale that the function provided 

35075 by this utility is available via the csplit utility (see csplit on page 314). Upon reconsideration of 

35076 the purpose of the User Portability Extension, it was decided to retain both this utility and the 

35077 csplit utility because users use both utilities and have historical expectations of their behavior. 

35078 Furthermore, the splitting on byte boundaries in split cannot be duplicated with the historical 

35079 csplit. 

35080 The text “split shall not delete the files it created with valid suffixes" would normally be 

35081 assumed, but since the related utility, csplit, does delete files under some circumstances, the 

35082 historical behavior of split is made explicit to avoid misinterpretation. 

35083 FUTURE DIRECTIONS 

35084 None. 

35085 SEE ALSO 

35086 csplit 

35087 CHANGE HISTORY 

35088 First released in Issue 2. 

35089 Issue 4 

35090 Aligned with the ISO/IEC 9945-2:1993 standard. 

35091 Issue 6 

35092 This utility is now marked as part of the User Portability Utilities option. 

35093 The APPLICATION USAGE section is added. 
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The obsolescent SYNOPSIS is removed. 


Commands and Utilities, Issue 6 


915 



strings 


Utilities 


35095 NAME 

35096 strings — find printable strings in files 

35097 SYNOPSIS 

35098 UP strings [-a] [— t format ] [— n number ] [file. . .] 

35099 


35100 DESCRIPTION 


35101 Notes to Reviewers 

35102 This section zvith side shading zvill not appear in the final copy. - Ed. 

35103 Dl, XCU, ERN 342 requests that the domain of this utility exclude internationalized strings. 

35104 The strings utility shall look for printable strings in regular files and shall write those strings to 

35105 standard output. A printable string is any sequence of four (by default) or more printable 

35106 characters terminated by a <newline> or NUL character. Additional implementation-dependent 

35107 strings may be written; see localedef. 


35108 OPTIONS 

35109 The strings utility shall conform to the System Interface Definitions volume of I 

35110 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

35111 The following options shall be supported: 


35112 -a Scan files in their entirety. If -a is not specified, it is implementation-dependent 

35113 what portion of each file is scanned for strings. 


35114 -n number Specify the minimum string length, where the number argument is a positive 

35115 decimal integer. The default shall be 4. 


35116 

35117 


—t format Write each string preceded by its byte offset from the start of the file. The format 

shall be dependent on the single character used as the format option-argument: 


35118 

d 

The 

35119 

o 

The 

35120 

X 

The 


offset shall be written in decimal, 
offset shall be written in octal, 
offset shall be written in hexadecimal. 


35121 OPERANDS 

35122 The following operand shall be supported: 

35123 file A path name of a regular file to be used as input. If no file operand is specified, the 

35124 strings utility shall read from the standard input. 

35125 STDIN 

35126 See the INPUT FILES section. 


35127 INPUT FILES 

35128 The input files named by the utility arguments or the standard input shall be regular files of any I 

35129 format. I 


35130 ENVIRONMENT VARIABLES 

35131 The following environment variables shall affect the execution of strings: 

35132 LANG Provide a default value for the internationalization variables that are unset or null. 

35133 If LANG is unset or null, the corresponding value from the implementation- 

35134 dependent default locale shall be used. If any of the internationalization variables 

35135 contains an invalid setting, the utility shall behave as if none of the variables had 

35136 been defined. 
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35137 LC_ALL If set to a non-empty string value, override the values of all the other 

35138 internationalization variables. 

35139 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

35140 characters (for example, single-byte as opposed to multi-byte characters in 

35141 arguments and input files) and to identify printable strings. 

35142 LC_MESSAGES 

35143 Determine the locale that should be used to affect the format and contents of 

35144 diagnostic messages written to standard error. 

35145 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

35146 ASYNCHRONOUS EVENTS 

35147 Default. 

35148 STDOUT 

35149 Strings found shall be written to the standard output, one per line. 

35150 When the -t option is not specified, the format of the output shall be: 

35151 "%s", <string> 

35152 With the -t o option, the format of the output shall be: 

35153 "%o %s", <byte offset>, <string> 

35154 With the -t x option, the format of the output shall be: 

35155 "%x %s", <byte offset>, <string> 

35156 With the -t d option, the format of the output shall be: 

35157 "%d %s", <byte offset>, <string> 

35158 STDERR 

35159 Used only for diagnostic messages. 

35160 OUTPUT FILES 

35161 None. 

35162 EXTENDED DESCRIPTION 

35163 None. 

35164 EXIT STATUS 

35165 The following exit values shall be returned: 

35166 0 Successful completion. 

35167 >0 An error occurred. 

35168 CONSEQUENCES OF ERRORS 

35169 Default. 
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35170 

35171 

35172 

35173 

35174 

35175 

35176 

35177 

35178 

35179 

35180 

35181 

35182 

35183 

35184 

35185 

35186 

35187 

35188 

35189 

35190 

35191 

35192 

35193 

35194 

35195 

35196 

35197 

35198 

35199 


APPLICATION USAGE 

By default the data area (as opposed to the text, "bss" or header areas) of a binary executable file 
is scanned. Implementations document which areas are scanned. 

Some historical implementations do not require NUL or <newline> character terminators for 
strings to permit those languages that do not use NUL as a string terminator to have their strings 
written. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

Apart from rationalizing the option syntax and slight difficulties with object and executable 
binary files, strings is specified to match historical practice closely. The -a and -n options were 
introduced to replace the non-conforming - and -number options. 

The -o option historically means different things on different implementations. Some use it to 
mean “offset in decimal", while others use it as "offset in octal". Instead of trying to decide which 
way would be least objectionable, the -t option was added. It was originally named -O to mean 
"offset", but was changed to -t to be consistent with od. 

The ISO C standard function isprint () is restricted to a domain of unsigned char. This volume of 
IEEE Std. 1003.1-200x requires implementations to write strings as defined by the current locale. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

nm 

CHANGE HISTORY 

First released in Issue 4. 


Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The obsolescent SYNOPSIS is removed. 

The normative text is reworded to avoid use of the term "must" for application requirements. 
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35200 NAME 

35201 strip — remove unnecessary information from executable files (DEVELOPMENT) 

35202 SYNOPSIS 

35203 SD strip file. . . 

35204 

35205 DESCRIPTION 

35206 The strip utility shall remove from executable files named by the file operands any information 

35207 the implementor deems unnecessary for execution of those files. The nature of that information 

35208 is unspecified. The effect of strip shall the same as the use of the -s option to cc, c89, or fort77. 

35209 OPTIONS 

35210 None. 

35211 OPERANDS 

35212 The following operand shall be supported: 


35213 

file 

A path name referring to an executable file. 

35214 STDIN 

35215 

Not used. 


35216 INPUT FILES 

35217 The input files shall be in the form of executable files successfully produced by any compiler 

35218 defined by this volume of IEEE Std. 1003.1-200x. 

35219 ENVIRONMENT VARIABLES 

35220 The following environment variables shall affect the execution of strip: 

35221 

35222 

35223 

35224 

35225 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

35226 

35227 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

35228 

35229 

35230 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

35231 

35232 

35233 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

35234 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


35235 ASYNCHRONOUS EVENTS 

35236 Default. 

35237 STDOUT 

35238 Not used. 

35239 STDERR 

35240 Used only for diagnostic messages. 
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35241 OUTPUT FILES 

35242 The strip utility shall produce executable files of unspecified format. 

35243 EXTENDED DESCRIPTION 

35244 None. 

35245 EXIT STATUS 

35246 The following exit values shall be returned: 

35247 0 Successful completion. 

35248 >0 An error occurred. 

35249 CONSEQUENCES OF ERRORS 

35250 Default. 

35251 APPLICATION USAGE 

35252 None. 

35253 EXAMPLES 

35254 None. 

35255 RATIONALE 

35256 Historically, this utility has been used to remove the symbol table from an executable file. It was 

35257 included since it is known that the amount of symbolic information can amount to several 

35258 megabytes; the ability to remove it in a portable manner was deemed important, especially for 

35259 smaller systems. 

35260 The behavior of strip is said to be the same as the -s option to a compiler. While the end result is 

35261 essentially the same, it is not required to be identical. The same effect can be achieved with 

35262 either -s during a compile or a strip on the final object file. 

35263 FUTURE DIRECTIONS 

35264 None. 

35265 SEE ALSO 

35266 ar, c89,fort77 

35267 CHANGE HISTORY 

35268 First released in Issue 2. 

35269 Issue 4 

35270 Aligned with the ISO/IEC 9945-2:1993 standard. 

35271 Issue 6 

35272 This utility is now marked as part of the Software Development Utilities option. 
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35273 NAME 

35274 stty — set the options for a terminal 

35275 SYNOPSIS 

35276 stty [ —a | —g] 


35277 stty operands 


35278 DESCRIPTION 

35279 The stty utility shall set or report on terminal I/O characteristics for the device that is its 

35280 standard input. Without options or operands specified, it shall report the settings of certain 

35281 characteristics, usually those that differ from implementation-dependent defaults. Otherwise, it 

35282 shall modify the terminal state according to the specified operands. Detailed information about 

35283 the modes listed in the first five groups below are described in the System Interface Definitions I 

35284 volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal Interface. Operands in the I 

35285 Combination Modes group (see Combination Modes on page 927) are implemented using 

35286 operands in the previous groups. Some combinations of operands are mutually-exclusive on 

35287 some terminal types; the results of using such combinations are unspecified. 

35288 Typical implementations of this utility require a communications line configured to use the 

35289 termios interface defined in the System Interfaces volume of IEEE Std. 1003.1-200x. On systems 

35290 where none of these lines are available, and on lines not currently configured to support the 

35291 termios interface, some of the operands need not affect terminal characteristics. 


35292 OPTIONS 

35293 The stty utility shall conform to the System Interface Definitions volume of I 

35294 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

35295 The following options shall be supported: 


35296 -a 


Write to standard output all the current settings for the terminal. 


35297 -g 

35298 

35299 

35300 


Write to standard output all the current settings in an unspecified form that can be 
used as arguments to another invocation of the stty utility on the same system. The 
form used shall not contain any characters that would require quoting to avoid 
word expansion by the shell; see Section 2.6 on page 49. 


35301 OPERANDS 

35302 The following operands shall be supported to set the terminal characteristics. 


35303 Control Modes 

35304 parenb (-parenb) Enable (disable) parity generation and detection. This has the effect of setting 

35305 (not setting) PARENB in the termios c_cflag field, as defined in the System I 

35306 Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General I 

35307 Terminal Interface. I 


35308 

35309 

35310 

35311 


parodd (-parodd) Select odd (even) parity. This shall have the effect of setting (not setting) 

PARODD in the termios c_cflag field, as defined in the System Interface I 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface. I 


35312 

35313 

35314 

35315 


cs5 cs6 cs7 cs8 Select character size, if possible. This shall have the effect of setting CS5, CS6, 

CS7, and CS8, respectively, in the termios c_cflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 


35316 number Set terminal baud rate to the number given, if possible. If the baud rate is set 

35317 to zero, the modem control lines shall not be longer asserted. This shall have 
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35320 

35321 

35322 

35323 

35324 

35325 

35326 

35327 

35328 

35329 

35330 

35331 

35332 

35333 

35334 

35335 

35336 

35337 

35338 

35339 

35340 

35341 

35342 

35343 

35344 

35345 

35346 

35347 

35348 

35349 

35350 

35351 

35352 

35353 

35354 

35355 

35356 

35357 

35358 

35359 

35360 

35361 
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the effect of setting the input and output termios baud rate values as defined 
in the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 
11, General Terminal Interface. 


ispeed number Set terminal input baud rate to the number given, if possible. If the input baud 
rate is set to zero, the input baud rate shall be specified by the value of the 
output baud rate. This shall have the effect of setting the input termios baud 
rate values as defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. 

ospeed number Set terminal output baud rate to the number given, if possible. If the output 
baud rate is set to zero, the modem control lines shall no longer be asserted. 
This shall have the effect of setting the output termios baud rate values as 
defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Chapter 11, General Terminal Interface. 


hupcl (-hupcl) Stop asserting modem control lines (do not stop asserting modem control 
lines) on last close. This shall have the effect of setting (not setting) HUPCL in 
the termios c_cflag field, as defined in the System Interface Definitions volume 
of IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. 


hup (-hup) 


Same as hupcl(-hupcl). 


cstopb (-cstopb) Use two (one) stop bits per character. This shall have the effect of setting (not 
setting) CSTOPB in the termios c_cflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 

cread (-cread) Enable (disable) the receiver. This shall have the effect of setting (not setting) 
CREAD in the termios c_cflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 

clocal (-clocal) Assume a line without (with) modem control. This shall have the effect of 
setting (not setting) CLOCAL in the termios c_cflag field, as defined in the 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, 
General Terminal Interface. 


It is unspecified whether stty shall report an error if an attempt to set a Control Mode fails. 


Input Modes 

ignbrk (-ignbrk) Ignore (do not ignore) break on input. This shall have the effect of setting (not 

setting) IGNBRK in the termios c_iflag field, as defined in the System Interface I 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface. I 

brkint (-brkint) Signal (do not signal) INTR on break. This shall have the effect of setting (not 

setting) BRKINT in the termios c_iflag field, as defined in the System Interface I 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface. I 

ignpar (-ignpar) Ignore (do not ignore) bytes with parity errors. This shall have the effect of 

setting (not setting) IGNPAR in the termios c_iflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 

General Terminal Interface. I 
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35362 

35363 

35364 

35365 

35366 

35367 

35368 

35369 

35370 

35371 

35372 

35373 

35374 

35375 

35376 

35377 

35378 

35379 

35380 

35381 

35382 

35383 

35384 

35385 

35386 

35387 

35388 

35389 

35390 

35391 

35392 

35393 

35394 

35395 

35396 

35397 

35398 

35399 

35400 
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parmrk (-parmrk) 

Mark (do not mark) parity errors. This shall have the effect of setting (not 
setting) PARMRK in the termios c_iflag field, as defined in the System 
Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General 
Terminal Interface. 

inpck (-inpck) Enable (disable) input parity checking. This shall have the effect of setting (not 
setting) INPCK in the termios c_iflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 

istrip (-istrip) Strip (do not strip) input characters to seven bits. This shall have the effect of 
setting (not setting) ISTRIP in the termios c_iflag field, as defined in the 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, 
General Terminal Interface. 

inlcr (-inlcr) Map (do not map) NL to CR on input. This shall have the effect of setting (not 
setting) INLCR in the termios c_iflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 


igncr (-igncr) Ignore (do not ignore) CR on input. This shall have the effect of setting (not 
setting) IGNCR in the termios c_iflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 


icrnl (-icrnl) Map (do not map) CR to NL on input. This shall have the effect of setting (not 
setting) ICRNL in the termios c_iflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 


ixon (-ixon) Enable (disable) START/STOP output control. Output from the system is 
stopped when the system receives STOP and started when the system receives 
START. This shall have the effect of setting (not setting) IXON in the termios 
c_iflag field, as defined in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. I 

ixany (-ixany) Allow any character to restart output. This shall have the effect of setting (not 

setting) IXANY in the termios c_iflag field, as defined in the System Interface I 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface. I 

ixoff (-ixoff) Request that the system send (not send) STOP characters when the input 
queue is nearly full and START characters to resume data transmission. This 
shall have the effect of setting (not setting) IXOFF in the termios c_iflag field, I 
as defined in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. I 
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Output Modes 

opost (-opost) Post-process output (do not post-process output; ignore all other output 
modes). This shall have the effect of setting (not setting) OPOST in the 
termios c_oflag field, as defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. 

ocrnl (-ocrnl) Map (do not map) CR to NL on output This shall have the effect of setting 
(not setting) OCRNL in the termios c_oflag field, as defined in the System 
Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General 
Terminal Interface. 

onocr (-onocr) Do not (do) output CR at column zero. This shall have the effect of setting (not 
setting) ONOCR in the termios c_oflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 

onlret (-onlret) The terminal newline key performs (does not perform) the CR function. This 
shall have the effect of setting (not setting) ONLRET in the termios c_oflag 
field, as defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. 

ofill (—ofill) Use fill characters (use timing) for delays. This shall have the effect of setting 

(not setting) OFILL in the termios c_oflag field, as defined in the System 
Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General 
Terminal Interface. 

of del (-of del) Fill characters are DELs (NULs). This shall have the effect of setting (not 

setting) OFDEL in the termios c_oflag field, as defined in the System Interface 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal 
Interface. 

crO crl cr2 cr3 Select the style of delay for CRs. This shall have the effect of setting (not 
setting) CRDLY to CR1, CR2, CR3, or CR4, respectively, in the termios c_oflag 
field, as defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. 

nlO nil Select the style of delay for NL. This has the effect of setting (not setting) 

NLDLY to NLO or NL1, respectively, in the termios c_oflag field, as defined in 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, 
General Terminal Interface. 

tabO tabl tab2 tab3 

Select the style of delay for horizontal tabs. This shall have the effect of setting 
(not setting) TABDLY to TABO, TAB1, TAB2, or TAB3, respectively, in the 
termios c_oflag field, as defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. Note that TAB3 
has the effect of expanding <tab>s to <space>s. 


onocr (-onocr) 


onlret (-onlret) 


ofill (-ofill) 


ofdel (-ofdel) 


crO crl cr2 cr3 


nlO nil 


bsO bsl 


ffO ffl 


Select the style of delay for backspaces. This shall have the effect of setting 
(not setting) BSDLY to BSO or BS1, respectively, in the termios c_oflag field, as I 
defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 11, General Terminal Interface. I 

Select the style of delay for form-feeds. This shall have the effect of setting 
(not setting) FFDLY to FFO or FF1, respectively, in the termios c_oflag field, as I 
defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 11, General Terminal Interface. I 
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35459 

35460 
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35464 

35465 

35466 

35467 

35468 

35469 

35470 

35471 

35472 

35473 

35474 
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35481 

35482 
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vtO vtl Select the style of delay for vertical-tabs. This shall have the effect of setting 

(not setting) VTDLY to VTO or VT1, respectively, in the termios c_oflag field, I 
as defined in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface. I 


Local Modes 

isig (-isig) Enable (disable) the checking of characters against the special control 

characters INTR, QUIT, and SUSP. This shall have the effect of setting (not 
setting) ISIG in the termios c_lflag field, as defined in the System Interface I 
Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface. I 

icanon (-icanon) Enable (disable) canonical input (ERASE and KILL processing). This shall 

have the effect of setting (not setting) ICANON in the termios c_lflag field, as I 
defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 11, General Terminal Interface. I 

iexten (-iexten) 

Enable (disable) any implementation-dependent special control characters not 
currently controlled by icanon, isig, ixon, or ixoff. This shall have the effect of 
setting (not setting) IEXTEN in the termios c_lflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 

echo (-echo) Echo back (do not echo back) every character typed. This shall have the effect 

of setting (not setting) ECHO in the termios c_lflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 

echoe (-echoe) The ERASE character visually erases (does not erase) the last character in the 
current line from the display, if possible. This shall have the effect of setting 
(not setting) ECHOE in the termios c_lflag field, as defined in the System I 
Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General I 
Terminal Interface. I 

echok (-echok) Echo (do not echo) NL after KILL character. This shall have the effect of 

setting (not setting) ECHOK in the termios c_lflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 

echonl (-echonl) Echo (do not echo) NL, even if echo is disabled. This shall have the effect of 

setting (not setting) ECHONL in the termios c_lflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 

noflsh (-nofish) Disable (enable) flush after INTR, QUIT, SUSP. This shall have the effect of 

setting (not setting) NOFLSH in the termios c_lflag field, as defined in the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface. I 

tostop (-tostop) Send SIGTTOU for background output. This shall have the effect of setting 

(not setting) TOSTOP in the termios c_lflag field, as defined in the System I 
Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General I 
Terminal Interface. I 
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35493 Special Control Character Assignments 


35494 

35495 

35496 

35497 

35498 

35499 

35500 


<control>-character string 

Set <control>-character to string. If <control>-character is one of the character sequences in I 
the first column of the following table, the corresponding System Interface Definitions I 

volume of IEEEStd. 1003.1-200x, Chapter 11, General Terminal Interface control character I 
from the second column shall be recognized. This has the effect of setting the corresponding 
element of the termios c_cc array (see the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 13, Headers, <termios.h>). I 


35501 Table 4-19 Control Character Names in stty 


35502 

Control Character 

c_cc Subscript 

Description 

35503 

eof 

VEOF 

EOF character 

35504 

eol 

VEOL 

EOL character 

35505 

erase 

VERASE 

ERASE character 

35506 

intr 

VINTR 

INTR character 

35507 

kill 

VKILL 

KILL character 

35508 

quit 

VQUIT 

QUIT character 

35509 

susp 

VSUSP 

SUSP character 

35510 

start 

VSTART 

START character 

35511 

stop 

VSTOP 

STOP character 


35512 

35513 

35514 

35515 

35516 

35517 

35518 


If string is a single character, the control character shall be set to that character. If string is 
the two-character sequence "" or the string nndef, the control character shall be set to 
_POSIX_VDISABLE , if it is in effect for the device; if _POSIX_VDISABLE is not in effect for 
the device, it shall be treated as an error. In the POSIX locale, if string is a two-character 
sequence beginning with circumflex (' ''), and the second character is one of those listed in 
the " ~ c" column of the following table, the control character shall be set to the 
corresponding character value in the Value column of the table. 


35519 Table 4-20 Circumflex Control Characters in stty 


35520 

A 

c 

Value 

A 

c 

Value 

A 

c 

Value 

35521 

a. 

A 

<SOH> 

1, 

L 

<FF> 

w. 

w 

<ETB> 

35522 

b. 

B 

<STX> 

m. 

M 

<CR> 

X, 

X 

<CAN> 

35523 

c. 

C 

<ETX> 

n. 

N 

<SO> 

y. 

Y 

<EM> 

35524 

d. 

D 

<EOT> 

o. 

O 

<SI> 

z. 

Z 

<SUB> 

35525 

e. 

E 

<ENQ> 

P, 

P 

<DLE> 

[ 


<ESC> 

35526 

f. 

F 

<ACK> 

q. 

Q 

<DC1> 

\ 


<FS> 

35527 

P, 

G 

<BEL> 

r. 

R 

<DC2> 

] 


<GS> 

35528 

h. 

H 

<BS> 

s. 

S 

<DC3> 

a 


<RS> 

35529 

i. 

I 

<HT> 

t. 

T 

<DC4> 



<US> 

35530 

j. 

J 

<LF> 

u. 

U 

<NAK> 



<DEL> 

35531 

k, 

K 

<VT> 

V, 

V 

<SYN> 





35532 

35533 

35534 

35535 


min number 
time number 

Set the value of min or time to number. MIN and TIME are used in non-canonical mode 
input processing (icanon). 
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35536 

35537 

35538 

35539 

35540 

35541 

35542 

35543 

35544 

35545 

35546 

35547 

35548 

35549 

35550 

35551 

35552 

35553 

35554 

35555 

35556 

35557 

35558 

35559 

35560 

35561 

35562 

35563 

35564 

35565 

35566 

35567 

35568 

35569 

35570 

35571 

35572 

35573 

35574 

35575 
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Combination Modes 

saved settings 

Set the current terminal characteristics to the saved settings produced by the -g option. 

evenp or parity 

Enable parenb and cs7; disable parodd. 
oddp 

Enable parenb, cs7, and parodd. 

-parity, -evenp, or -oddp 

Disable parenb, and set cs8. 

xsi raw (-raw or cooked) 

Enable (disable) raw input and output. Raw mode shall be equivalent to setting: 

stty cs8 erase kill intr \ 

quit eof eol —post —inpck 

nl (-nl) 

Enable (disable) icrnl. In addition, -nl unsets inlcr and igncr. 

xsi tabs (-tabs or tab3) 

Preserve tabs (expand to spaces) when printing. 

ek Reset ERASE and KILL characters back to system defaults. 

sane Reset all modes to some reasonable, unspecified, values. 

STDIN 

Although no input is read from standard input, standard input is used to get the current 
terminal I/O characteristics and to set new terminal I/O characteristics. 

INPUT FILES 

None. 


ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of stty: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE This variable determines the locale for the interpretation of sequences of bytes of 
text data as characters (for example, single-byte as opposed to multi-byte 
characters in arguments) and which characters are in the class print. 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 
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35576 ASYNCHRONOUS EVENTS 

35577 Default. 

35578 STDOUT 

35579 If operands are specified, no output shall be produced. 

35580 If the -g option is specified, stty shall write to standard output the current settings in a form that 

35581 can be used as arguments to another instance of stty on the same system. 

35582 If the -a option is specified, all of the information as described in the OPERANDS section shall 

35583 be written to standard output. Unless otherwise specified, this information shall be written as 

35584 <space>-separated tokens in an unspecified format, on one or more lines, with an unspecified 

35585 number of tokens per line. Additional information may be written. 

35586 If no options or operands are specified, an unspecified subset of the information written for the 

35587 -a option shall be written. 

35588 If speed information is written as part of the default output, or if the -a option is specified and if 

35589 the terminal input speed and output speed are the same, the speed information shall be written 

35590 as follows: 

35591 "speed %d baud;", <speed> 

35592 Otherwise, speeds shall be written as: 

35593 "ispeed %d baud; ospeed %d baud;", <ispeed>, <ospeed> 

35594 In locales other than the POSIX locale, the word baud may be changed to something more 

35595 appropriate in those locales. 

35596 If control characters are written as part of the default output, or if the -a option is specified, 

35597 control characters shall be written as: 

35598 "%s = %s;", <control-character name>, <value> 

35599 where <value is either the character, or some visual representation of the character if it is non- 

35600 printable, or the string undef if the character is disabled. 

35601 STDERR 

35602 Used only for diagnostic messages. 

35603 OUTPUT FILES 

35604 None. 

35605 EXTENDED DESCRIPTION 

35606 None. 

35607 EXIT STATUS 

35608 The following exit values shall be returned: 

35609 0 The terminal options were read or set successfully. 

35610 >0 An error occurred. 

35611 CONSEQUENCES OF ERRORS 

35612 Default. 
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35613 

35614 

35615 

35616 

35617 

35618 

35619 

35620 

35621 

35622 

35623 

35624 

35625 

35626 

35627 

35628 

35629 

35630 

35631 

35632 

35633 

35634 

35635 

35636 

35637 

35638 

35639 

35640 

35641 

35642 

35643 

35644 

35645 

35646 

35647 

35648 

35649 

35650 

35651 

35652 

35653 

35654 

35655 

35656 

35657 

35658 
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APPLICATION USAGE 

The -g flag is designed to facilitate the saving and restoring of terminal state from the shell level. 
For example, a program may: 

saveterm="$(stty —g)" # save terminal state 

stty (new settings ) # set new state 

# . . . 

stty $saveterm # restore terminal state 

Since the format is unspecified, the saved value is not portable across systems. 

Since the -a format is so loosely specified, scripts that save and restore terminal settings should 
use the -g option. 

EXAMPLES 

None. 

RATIONALE 

The original stty description was taken directly from System V and reflected the System V 
terminal driver termio. It has been modified to correspond to the terminal driver termios. 

Since the System Interface Definitions volume of IEEE Std. 1003.1-200x does not specify any 
output modes, they are not specified in this volume of IEEE Std. 1003.1-200x either. 
Implementations are expected to provide stty operands corresponding to all of the output modes 
they support. 

In many ways outside the scope of this volume of IEEE Std. 1003.1-200x, stty is primarily used to 
tailor the user interface of the terminal, such as selecting the preferred ERASE and KILL 
characters. As an application programming utility, stty can be used within shell scripts to alter 
the terminal settings for the duration of the script. 

The termios section states that individual disabling of control characters is possible through the 
option _POSIX_VDISABLE. If enabled, two conventions currently exist for specifying this: 
System V uses and BSD uses undef. Both are accepted by stty in this volume of 

IEEE Std. 1003.1-200x. The other BSD convention of using the letter ' u' was rejected because it 
conflicts with the actual letter 'u', which is an acceptable value for a control character. 

Early proposals did not specify the mapping of " * c" to control characters because the control 
characters were not specified in the POSIX locale character set description file requirements. The 
control character set is now specified in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Chapter 3, Definitions so the historical mapping is specified. Note that 
although the mapping corresponds to control-character key assignments on many terminals that 
use the ISO/IEC 646:1991 standard (or ASCII) character encodings, the mapping specified here 
is to the control characters, not their keyboard encodings. 

Since termios supports separate speeds for input and output, two new options were added to 
specify each distinctly. 

Some historical implementations use standard input to get and set terminal characteristics; 
others use standard output. Since input from a login TTY is usually restricted to the owner while 
output to a TTY is frequently open to anyone, using standard input provides fewer chances of 
accidentally (or maliciously) altering the terminal settings of other users. Using standard input 
also allows stty -a and stty -g output to be redirected for later use. Therefore, usage of standard 
input is required by this volume of IEEE Std. 1003.1-200x. 

The tostop option is the only option that requires job control to be effective, and thus could have 
gone into the UPE as a modification to stty, but since all other terminal control features are in the 
base standard, tostop was included as well. 
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35659 FUTURE DIRECTIONS 

35660 None. I 

35661 SEE ALSO 

35662 The System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, General Terminal I 

35663 Interface I 

35664 CHANGE HISTORY 

35665 First released in Issue 2. 

35666 Issue 4 

35667 Aligned with the ISO/IEC 9945-2:1993 standard. 

35668 Issue 5 

35669 The description of tabs is clarified. 

35670 FUTURE DIRECTIONS section added. 

35671 Issue 6 

35672 The legacy items iuclc(-iuclc), xcase, olcuc(-olcuc), lcase(-lcase), and LCASE(-LCASE), are 

35673 removed. 
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35674 NAME 

35675 tabs — set terminal tabs 

35676 SYNOPSIS 

35677 UP xsi tabs [ — n | —a | —a2 | —c | —c2 | —c3 | —f | —p | —s | —u][+m[n]] [-T type] 

35678 tabs [-T type] [ +[n]] nl[,n2,...] 

35679 

35680 DESCRIPTION 

35681 The tabs utility shall display a series of characters that first clears the hardware terminal tab 

35682 xsi settings and then initializes the tab stops at the specified positions and optionally adjusts the 

35683 margin. 

35684 The phrase "tab-stop position N" shall be taken to mean that, from the start of a line of output, 

35685 tabbing to position N shall cause the next character output to be in the (N+l)th column position 

35686 on that line. The maximum number of tab stops allowed is terminal-dependent. 

35687 It need not be possible to implement tabs on certain terminals. If the terminal type obtained from 

35688 the TERM environment variable or -T option represents such a terminal, an appropriate 

35689 diagnostic message shall be written to standard error and tabs shall exit with a status greater 

35690 than zero. 


-n 


-a 


-a2 


35691 OPTIONS 

35692 

35693 XSI 

35694 

35695 

35696 

35697 

35698 

35699 

35700 

35701 XSI 

35702 

35703 XSI 

35704 

35705 XSI 

35706 

35707 XSI 

35708 

35709 XSI 

35710 

35711 XSI 

35712 

35713 XSI 

35714 

35715 XSI 

35716 


The tabs utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines, except for various extensions: the 
options -a2, -c2, and -c3 are multi-character and +m [n] uses a leading plus sign and an 
optional option-argument. 

The following options shall be supported: 

Specify repetitive tab stops separated by a uniform number of column positions, n, 
where n is a single-digit decimal number. The default usage of tabs with no 
arguments shall be equivalent to tabs-8. When -0 is used, the tab stops shall be 
cleared and no new ones set. 

1.10.16.36.72 

Assembler, applicable to some mainframes. 

1.10.16.40.72 

Assembler, applicable to some mainframes. 


-c 


-c2 


-c3 


-f 


-s 


1.8.12.16.20.55 
COBOL, normal format. 

1,6,10,14,49 

COBOL, compact format (columns 1-6 omitted). 
1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 

COBOL compact format (columns 1-6 omitted), with more tabs than -c2. 

1,7,11,15,19,23 

FORTRAN 

1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 

PL/1 

1.10.55 
SNOBOL 
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35717 XSI 

35718 

-u 

1,12,20,44 

Assembler, applicable to some mainframes. 

35719 

35720 

35721 

-T type 

Indicate the type of terminal. If this option is not supplied and the TERM variable 
is unset or null, an unspecified default terminal type shall be used. The setting of 
type shall take precedence over the value in TERM. 

35722 XSI UN 

35723 

35724 

35725 

35726 

+m[n] 

Reset the margin. The margin argument can be used for some terminals. It shall 
cause all tabs to be moved over n columns by making column n+1 the left margin. 
If n is omitted, the default shall be 10. The normal (leftmost) margin on most 
terminals is obtained by +m0. The margin for most terminals is reset only when 
the +m flag is given explicitly. 

35727 OPERANDS 

35728 The following operand shall be supported: 

35729 

35730 

35731 

35732 

35733 

35734 

nl[,n2 ,...] 

A single command line argument that consists of tab-stop values separated using 
either commas or <blank> characters. The application shall ensure that the tab- 
stop values are positive decimal integers in strictly ascending order. If any number 
(except the first one) is preceded by a plus sign, it is taken as an increment to be 
added to the previous value. For example, the tab lists 1,10,20,30 and 1,10,+10,+10 
are considered to be identical. 

35735 STDIN 

35736 

Not used. 


35737 INPUT FILES 

35738 None. 


35739 ENVIRONMENT VARIABLES 

35740 The following environment variables shall affect the execution of tabs: 

35741 

35742 

35743 

35744 

35745 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

35746 

35747 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

35748 

35749 

35750 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

35751 

35752 

35753 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

35754 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

35755 

35756 

TERM 

Determine the terminal type. If this variable is unset or null, and if the -T option is 
not specified, an unspecified default terminal type shall be used. 


35757 ASYNCHRONOUS EVENTS 

35758 Default. 
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35759 

35760 

35761 

35762 

35763 

35764 

35765 

35766 

35767 

35768 

35769 

35770 

35771 

35772 

35773 

35774 

35775 

35776 

35777 

35778 

35779 

35780 

35781 

35782 

35783 

35784 

35785 

35786 

35787 

35788 

35789 

35790 

35791 

35792 

35793 

35794 

35795 

35796 

35797 

35798 

35799 

35800 

35801 


STDOUT 

If standard output is a terminal, the appropriate sequence to clear and set the tab stops may be 
written to standard output in an unspecified format. If standard output is not a terminal, 
undefined results occur. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

This utility makes use of the terminal's hardware tabs and the stty tabs option. 

This utility is not recommended for application use. 

Some integrated display units might not have escape sequences to set tab stops, but may be set 
by internal system calls. On these terminals, tabs works if standard output is directed to the 
terminal; if output is directed to another file, however, tabs fails. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

Consideration was given to having the tput utility handle all of the functions described in tabs. 
However, the separate tabs utility was retained because it seems more intuitive to use a 
command named tabs than tput with a new option. The POSIX Shell and Utilities tput does not 
support setting or clearing tabs, and no known historical version of tabs supports the capability 
of setting arbitrary tab stops. 

The System V tabs interface is very complex; the version in this volume of IEEE Std. 1003.1-200x 
has a reduced feature list. There was considerable sentiment for specifying only a means of 
resetting the tabs back to a known state—presumably the "standard" of tabs every eight 
positions. The following features were omitted: 

• Setting tab stops tailored for certain programming languages; the standard developers were 
concerned that it would be difficult to decide which languages to include and where the tabs 
should be. 

• Setting tab stops via the first line in a file, using — file. Since even the SVID has no complete 
explanation of this feature, it is doubtful that it is in widespread use. 

• Setting the left margin using +m n. As this does not work with all terminal types, it was 
omitted. 
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35802 In an early proposal, a -t tablist option was added for consistency with expand; this was later 

35803 removed when inconsistencies with the historical list of tabs were identified. 

35804 Consideration was given to adding a -p option that would output the current tab settings so 

35805 that they could be saved and then later restored. This was not accepted because querying the tab 

35806 stops of the terminal is not a capability in historical terminfo or termcap facilities and might not be 

35807 supported on a wide range of terminals. 

35808 FUTURE DIRECTIONS 

35809 None. 

35810 SEE ALSO 

35811 expand, stty, unexpand 

35812 CHANGE HISTORY 

35813 First released in Issue 2. 

35814 Issue 4 

35815 Aligned with the ISO/IEC 9945-2:1993 standard. 

35816 Issue 6 

35817 This utility is now marked as part of the User Portability Utilities option. 

35818 The normative text is reworded to avoid use of the term "must” for application requirements. 
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35819 NAME 

35820 tail — copy the last part of a file 

35821 SYNOPSIS 

35822 tail [—f] [ — c number \ —n number ] [file] 


35823 DESCRIPTION 

35824 The tail utility shall copy its input file to the standard output beginning at a designated place. 

35825 Copying shall begin at the point in the file indicated by the -c number or -n number options. The 

35826 option-argument number shall be counted in units of lines or bytes, according to the options -n 

35827 and -c. Both line and byte counts start from 1. 

35828 Tails relative to the end of the file may be saved in an internal buffer, and thus may be limited in 

35829 length. Such a buffer, if any, is no smaller than |LINE_MAX}*10 bytes. 


35830 OPTIONS 

35831 The tail utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

35832 Section 12.2, Utility Syntax Guidelines. I 

35833 The following options shall be supported: 


35834 -c number The application shall ensure that the number option-argument is a decimal integer I 

35835 whose sign affects the location in the file, measured in bytes, to begin the copying: I 


35836 

Sign 

Copying Starts 

35837 

+ 

Relative to the beginning of the file. 

35838 

- 

Relative to the end of the file. 

35839 

none 

Relative to the end of the file. 


35840 The origin for counting shall be 1; that is, -c +1 represents the first byte of the file, 

35841 -c -1 the last. 


35842 -f 

35843 

35844 

35845 

35846 

35847 


If the input file is a regular file or if the file operand specifies a FIFO, do not 
terminate after the last line of the input file has been copied, but read and copy 
further bytes from the input file when they become available. If no file operand is 
specified and standard input is a pipe, the -f option shall be ignored. If the input 
file is not a FIFO, pipe, or regular file, it is unspecified whether or not the -f option 
shall be ignored. 


35848 

35849 

35850 


-n number This option is equivalent to -c number, except the starting location in the file shall 
be measured in lines instead of bytes. The origin for counting shall be 1; that is, -n 
+1 represents the first line of the file, -n -1 the last. 


35851 If neither -c nor -n is specified, -n 10 shall be assumed. 


35852 OPERANDS 

35853 The following operand shall be supported: 

35854 file A path name of an input file. If no file operands are specified, the standard input 

35855 shall be used. 


35856 STDIN 

35857 The standard input shall be used only if no file operands are specified. See the INPUT FILES 

35858 section. 
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35859 INPUT FILES 

35860 If the -c option is specified, the input file can contain arbitrary data; otherwise, the input file I 

35861 shall be a text file. I 


35862 ENVIRONMENT VARIABLES 

35863 The following environment variables shall affect the execution of tail: 


35864 

35865 

35866 

35867 

35868 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


35869 

35870 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


35871 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

35872 characters (for example, single-byte as opposed to multi-byte characters in 

35873 arguments and input files). 

35874 LC_MESSAGES 

35875 Determine the locale that should be used to affect the format and contents of 

35876 diagnostic messages written to standard error. 

35877 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

35878 ASYNCHRONOUS EVENTS 

35879 Default. 


35880 STDOUT 

35881 The designated portion of the input file shall be written to standard output. 

35882 STDERR 

35883 Used only for diagnostic messages. 

35884 OUTPUT FILES 

35885 None. 


35886 EXTENDED DESCRIPTION 

35887 None. 


35888 EXIT STATUS 

35889 The following exit values shall be returned: 

35890 0 Successful completion. 

35891 >0 An error occurred. 


35892 CONSEQUENCES OF ERRORS 

35893 Default. 
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35894 APPLICATION USAGE 

35895 The -c option should be used with caution when the input is a text file containing multi-byte 

35896 characters; it may produce output that does not start on a character boundary. 

35897 Although the input file to tail can be any type, the results might not be what would be expected 

35898 on some character special device files or on file types not described by the System Interfaces 

35899 volume of IEEE Std. 1003.1-200x. Since this volume of IEEE Std. 1003.1-200x does not specify the 

35900 block size used when doing input, tail need not read all of the data from devices that only 

35901 perform block transfers. 

35902 EXAMPLES 

35903 The -f option can be used to monitor the growth of a file that is being written by some other 

35904 process. For example, the command: 

35905 tail -f fred 

35906 prints the last ten lines of the file fred, followed by any lines that are appended to fred between 

35907 the time tail is initiated and killed. As another example, the command: 

35908 tail -f —c 15 fred 

35909 prints the last 15 bytes of the file fred, followed by any bytes that are appended to fred between 

35910 the time tail is initiated and killed. 

35911 RATIONALE 

35912 This version of tail was created to allow conformance to the Utility Syntax Guidelines. The 

35913 historical -b option was omitted because of the general non-portability of block-sized units of 

35914 text. The -c option historically meant "characters", but this volume of IEEE Std. 1003.1-200x 

35915 indicates that it means "bytes". This was selected to allow reasonable implementations when 

35916 multi-byte characters are possible; it was not named -b to avoid confusion with the historical 

35917 -b. 

35918 The origin of counting both lines and bytes is 1, matching all widespread historical 

35919 implementations. 

35920 The restriction on the internal buffer is a compromise between the historical System V 

35921 implementation of 4 096 bytes and the BSD 32 768 bytes. 

35922 The -f option has been implemented as a loop that sleeps for 1 second and copies any bytes that 

35923 are available. This is sufficient, but if more efficient methods of determining when new data are 

35924 available are developed, implementations are encouraged to use them. 

35925 Historical documentation indicates that tail ignores the -f option if the input file is a pipe (pipe 

35926 and FIFO on systems that support FIFOs). On BSD-based systems, this has been true; on System 

35927 V-based systems, this was true when input was taken from standard input, but it did not ignore 

35928 the -f flag if a FIFO was named as the file operand. Since the -f option is not useful on pipes and 

35929 all historical implementations ignore -f if no file operand is specified and standard input is a 

35930 pip e / this volume of IEEE Std. 1003.1-200x requires this behavior. However, since the -f option is 

35931 useful on a FIFO, this volume of IEEE Std. 1003.1-200x also requires that if standard input is a 

35932 FIFO or a FIFO is named, the -f option shall not be ignored. Although historical behavior does 

35933 not ignore the -f option for other file types, this is unspecified so that implementations are 

35934 allowed to ignore the -f option if it is known that the file cannot be extended. 

35935 This was changed to the current form based on comments noting that -c was almost never used 

35936 without specifying a number and that there was no need to specify -1 if -n number was given. 
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35937 FUTURE DIRECTIONS 

35938 None. 

35939 SEE ALSO 

35940 head 

35941 CHANGE HISTORY 

35942 First released in Issue 2. 

35943 Issue 4 

35944 Aligned with the ISO/IEC 9945-2:1993 standard. 

35945 Issue 6 

35946 The obsolescent SYNOPSIS lines and associated text are removed. 

35947 The normative text is reworded to avoid use of the term "must” for application requirements. 
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35948 NAME 

35949 talk — talk to another user 

35950 SYNOPSIS 

35951 UP talk address [ terminal ] 

35952 

35953 DESCRIPTION 

35954 The talk utility is a two-way, screen-oriented communication program. 

35955 When first invoked, talk shall send a message similar to: 

35956 Message from <unspecified string> 

35957 talk: connection requested by your_address 

35958 talk: respond with: talk your_address 

35959 to the specified address . At this point, the recipient of the message can reply by typing: 

35960 talk your_address 

35961 Once communication is established, the two parties can type simultaneously, with their output 

35962 displayed in separate regions of the screen. Characters shall be processed as follows: 

35963 • Typing the alert character shall alert the recipient's terminal. 

35964 • Typing <control>-L shall cause the sender's screen regions to be refreshed. 

35965 • Typing the erase and kill characters shall affect the sender's terminal in the manner described 

35966 by the termios interface in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

35967 Chapter 11, General Terminal Interface. I 

35968 • Typing the interrupt or end-of-file characters shall terminate the local talk utility. Once the 

35969 talk session has been terminated on one side, the other side of the talk session shall be notified 

35970 that the talk session has been terminated and shall be able to do nothing except exit. 

35971 • Typing characters from LC_CTYPE classifications print or space shall cause those characters 

35972 to be sent to the recipient's terminal. 

35973 • When and only when the stty iexten local mode is enabled, the existence and processing of 

35974 additional special control characters and multi-byte or single-byte functions shall be 

35975 implementation-dependent. 

35976 • Typing other non-printable characters shall cause implementation-dependent sequences of 

35977 printable characters to be sent to the recipient's terminal. 

35978 Permission to be a recipient of a talk message can be denied or granted by use of the mesg utility. 

35979 However, a user's privilege may further constrain the domain of accessibility of other users' 

35980 terminals. The talk utility shall fail when the user lacks the appropriate privileges to perform the 

35981 requested action. 

35982 Certain block-mode terminals do not have all the capabilities necessary to support the 

35983 simultaneous exchange of messages required for talk. When this type of exchange cannot be 

35984 supported on such terminals, the implementation may support an exchange with reduced levels 

35985 of simultaneous interaction or it may report an error describing the terminal-related deficiency. 

35986 OPTIONS 

35987 None. 
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35988 OPERANDS 

35989 The following operands shall be supported: 


35990 

35991 

35992 


address The recipient of the talk session. One form of address is the <user name>, as returned 

by the zvho utility. Other address formats and how they are handled are 
unspecified. 


35993 

35994 

35995 

35996 


terminal If the recipient is logged in more than once, the terminal argument can be used to 
indicate the appropriate terminal name. If terminal is not specified, the talk message 
shall be displayed on one or more accessible terminals in use by the recipient. The 
format of terminal shall be the same as that returned by the zvho utility. 


35997 STDIN 

35998 Characters read from standard input shall be copied to the recipient's terminal in an unspecified 

35999 manner. If standard input is not a terminal, talk shall write a diagnostic message and exit with a 

36000 non-zero status. 


36001 INPUT FILES 

36002 None. 


36003 ENVIRONMENT VARIABLES 

36004 The following environment variables shall affect the execution of talk: 


36005 

36006 

36007 

36008 

36009 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


36010 

36011 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


36012 

36013 

36014 

36015 


LCJZTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). If the recipient's locale does not use an LC_CTYPE 
equivalent to the sender's, the results are undefined. 


36016 LC_MESSAGES 

36017 Determine the locale that should be used to affect the format and contents of 

36018 diagnostic messages written to standard error and informative messages written to 

36019 standard output. 

36020 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

36021 TERM Determine the name of the invoker's terminal type. If this variable is unset or null, 

36022 an unspecified default terminal type shall be used. 


36023 ASYNCHRONOUS EVENTS 

36024 When the talk utility receives a SIGINT signal, the utility shall terminate and exit with a zero 

36025 status. It shall take the standard action for all other signals. 


36026 STDOUT 

36027 If standard output is a terminal, characters copied from the recipient's standard input may be 

36028 written to standard output. Standard output also may be used for diagnostic messages. If 

36029 standard output is not a terminal, talk shall exit with a non-zero status. 
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36030 STDERR 

36031 None. 

36032 OUTPUT FILES 

36033 None. 

36034 EXTENDED DESCRIPTION 

36035 None. 

36036 EXIT STATUS 

36037 The following exit values shall be returned: 

36038 0 Successful completion. 

36039 >0 An error occurred or talk was invoked on a terminal incapable of supporting it. 

36040 CONSEQUENCES OF ERRORS 

36041 Default. 

36042 APPLICATION USAGE 

36043 Because the handling of non-printable, non-<space> characters is tied to the stty description of 

36044 iexten, implementation extensions within the terminal driver can be accessed. For example, 

36045 some implementations provide line editing functions with certain control character sequences. 

36046 Application writers should note that this utility need not be provided on systems that do not 

36047 support the User Portability Utilities option. 

36048 EXAMPLES 

36049 None. 

36050 RATIONALE 

36051 The write utility was included in this volume of IEEE Std. 1003.1-200x since it can be 

36052 implemented on all terminal types. The talk utility, which cannot be implemented on certain 

36053 terminals, was considered to be a "better" communications interface. Both of these programs are 

36054 in widespread use on historical implementations. Therefore, both utilities have been specified. 

36055 All references to networking abilities (talking to a user on another system) were removed as 

36056 being outside the scope of this volume of IEEE Std. 1003.1-200x. 

36057 Historical BSD and System V versions of talk terminate both of the conversations when either 

36058 user breaks out of the session. This can lead to adverse consequences if a user unwittingly 

36059 continues to enter text that is interpreted by the shell when the other terminates the session. 

36060 Therefore, the version of talk specified by this volume of IEEE Std. 1003.1-200x requires both 

36061 users to terminate their end of the session explicitly. 

36062 Only messages sent to the terminal of the invoking user can be internationalized in any way: 

36063 • The original "Message from <nnspecified string> ..!' message sent to the terminal of the 

36064 recipient cannot be internationalized because the environment of the recipient is as yet 

36065 inaccessible to the talk utility. The environment of the invoking party is irrelevant. 

36066 • Subsequent communication between the two parties cannot be internationalized because the 

36067 two parties may specify different languages in their environment (and non-portable 

36068 characters cannot be mapped from one language to another). 

36069 • Neither party can be required to communicate in a language other than C and/or the one 

36070 specified by their environment because unavailable terminal hardware support (for example, 

36071 fonts) may be required. 

36072 The text in the STDOUT section reflects the usage of the verb "display" in this section; some talk 

36073 implementations actually use standard output to write to the terminal, but this volume of 
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IEEE Std. 1003.1-200x does not require that to be the case. 

The format of the terminal name is unspecified, but the descriptions of ps, talk, who, and write 
require that they all use or accept the same format. 

The handling of non-printable characters is partially implementation-dependent because the 
details of mapping them to printable sequences is not needed by the user. Historical 
implementations, for security reasons, disallow the transmission of non-printable characters that 
may send commands to the other terminal. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mesg, who, write, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, I 
General Terminal Interface I 

CHANGE HISTORY 

First released in Issue 4. 


Issue 6 

This utility is now marked as part of the User Portability Utilities option. 
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36090 NAME 

36091 tee — duplicate standard input 

36092 SYNOPSIS 

36093 tee [—ai ][ file ... ] 

36094 DESCRIPTION 

36095 The tee utility shall copy standard input to standard output, making a copy in zero or more files. 

36096 The tee utility shall not buffer output. 

36097 The options determine whether the specified files are overwritten or appended to. 

36098 OPTIONS 

36099 The tee utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

36100 Section 12.2, Utility Syntax Guidelines. I 

36101 The following options shall be supported: 

36102 -a Append the output to the files rather than overwriting them. 

36103 -i Ignore the SIGINT signal. 

36104 OPERANDS 

36105 The following operands shall be supported: 

36106 file A path name of an output file. Processing of at least 13 file operands shall be 

36107 supported. 

36108 STDIN 

36109 The standard input can be of any type. 


36110 INPUT FILES 

36111 None. 

36112 ENVIRONMENT VARIABLES 


36113 

The following environment variables shall affect the execution of tee: 

36114 

36115 

36116 

36117 

36118 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

36119 

36120 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

36121 

36122 

36123 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

36124 

36125 

36126 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

36127 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


36128 ASYNCHRONOUS EVENTS 

36129 Default, except that if the -i option was specified, SIGINT shall be ignored. 
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36130 

36131 

36132 

36133 

36134 

36135 

36136 

36137 

36138 

36139 

36140 

36141 

36142 

36143 

36144 

36145 

36146 

36147 

36148 

36149 

36150 

36151 

36152 

36153 

36154 

36155 

36156 

36157 

36158 

36159 

36160 

36161 

36162 

36163 

36164 

36165 

36166 

36167 

36168 

36169 


STDOUT 

The standard output shall be a copy of the standard input. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

If any file operands are specified, the standard input shall be copied to each named file. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The standard input was successfully copied to all output files. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 

If a write to any successfully opened file operand fails, writes to other successfully opened file 
operands and standard output shall continue, but the exit status shall be non-zero. Otherwise, 
the default actions specified in Section 1.11 on page 25 apply. 

APPLICATION USAGE 

The tee utility is usually used in a pipeline, to make a copy of the output of some utility. 

The file operand is technically optional, but tee is no more useful than cat when none is specified. 

EXAMPLES 

Save an unsorted intermediate form of the data in a pipeline: 

... | tee unsorted I sort > sorted 

RATIONALE 

The buffering requirement means that tee is not allowed to use ISO C standard fully buffered or 
line-buffered writes. It does not mean that tee has to do 1-byte reads followed by 1-byte writes. 

It should be noted that early versions of BSD ignore any invalid options and accept a single ' 
as an alternative to -i. They also print a message if unable to open a file: 

"tee: cannot access %s\n", <pathname> 

Historical implementations ignore write errors. This is explicitly not permitted by this volume of 
IEEE Std. 1003.1-200x. 

Some historical implementations use 0_APPEND when providing append mode; others use the 
lseek () function to seek to the end of file after opening the file without 0_APPEND. This volume 
of IEEE Std. 1003.1-200x requires functionality equivalent to using 0_APPEND; see Section 
1.7.1.4 on page 11. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

cat 

CHANGE HISTORY 

First released in Issue 2. 


944 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


tee 


36170 Issue 4 

36171 Aligned with the ISO/IEC 9945-2:1993 standard. 
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36172 NAME 

36173 test — evaluate expression 

36174 SYNOPSIS 

36175 test [expression] 

36176 [ [expression] ] 

36177 DESCRIPTION 

36178 The test utility shall evaluate the expression and indicates the result of the evaluation by its exit 

36179 status. An exit status of zero indicates that the expression evaluated as true and an exit status of 

36180 1 indicates that the expression evaluated as false. 

36181 In the second form of the utility, which uses " [ ] " rather than test, the application shall ensure I 

36182 that the square brackets are separate arguments. I 

36183 OPTIONS 

36184 The test utility shall not recognize the "—" argument in the manner specified by guideline 10 in I 

36185 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax I 

36186 Guidelines. I 

36187 No options shall be supported. 

36188 OPERANDS 

36189 The application shall ensure that all operators and elements of primaries are presented as I 

36190 separate arguments to the test utility. I 


36191 The following primaries can be used to construct expression: 


36192 

-b file 

True if file exists and is a block special file. 

36193 

-cfile 

True if file exists and is a character special file. 

36194 

-dfile 

True if file exists and is a directory. 

36195 

-efile 

True if file exists. 

36196 

-f file 

True if file exists and is a regular file. 

36197 

-g file 

True if file exists and its set group ID flag is set. 

36198 

-hfile 

True if file exists and is a symbolic link. 

36199 

-n string 

True if the length of string is non-zero. 

36200 

-Pfile 

True it file is a named pipe (FIFO). 

36201 

36202 

-rfile 

True if file exists and is readable. True shall indicate that permission to read from 
file will be granted, as defined in Section 1.7.1.4 on page 11. 

36203 

-sfile 

True if file exists and has a size greater than zero. 

36204 

36205 

36206 

- tfile_descriptor 

True if the file whose file descriptor number is file_descriptor is open and is 
associated with a terminal. 

36207 

-ufile 

True if file exists and its set-user-ID flag is set. 

36208 

36209 

-wfile 

True if file exists and is writable. True shall indicate that permission to write from 
file will be granted, as defined in Section 1.7.1.4 on page 11. 

36210 

36211 

36212 

-xfile 

True if file exists and is executable. True if file exists and is executable. True shall 
indicate that permission to execute file will be granted, as defined in Section 1.7.1.4 
on page 11. li file is a directory, true shall indicate that permission to search file 
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36213 will be granted. I 

36214 -z string True if the length of string string is zero. 

36215 string True if the string string is not the null string. 

36216 si = s2 True if the strings si and s2 are identical. 

36217 si != s2 True if the strings si and s2 are not identical. 

36218 nl -eq n2 True if the integers nl and n2 are algebraically equal. 

36219 nl -ne n2 True if the integers nl and n2 are not algebraically equal. 

36220 nl -gt n2 True if the integer nl is algebraically greater than the integer n2. 

36221 nl -ge n2 True if the integer nl is algebraically greater than or equal to the integer n2. 

36222 nl -It n2 True if the integer nl is algebraically less than the integer n2. 

36223 nl -le n2 True if the integer nl is algebraically less than or equal to the integer n2. 

36224 xsi expressionl -a expression2 

36225 True if both expressionl and expression2 are true. The -a binary primary is left 

36226 associative. It has a higher precedence than -o. 

36227 xsi expressionl -o expression2 

36228 True if either expressionl or expression2 is true. The -o binary primary is left 

36229 associative. 

36230 With the exception of the -h file primary, if a file argument is a symbolic link, test shall evaluate I 

36231 the expression by resolving the symbolic link and using the file referenced by the link. I 

36232 These primaries can be combined with the following operators: I 

36233 ! expression True if expression is false. 

36234 xsi ( expression ) True if expression is true. The parentheses can be used to alter the normal 

36235 precedence and associativity. 

36236 The primaries with two elements of the form: 

36237 —primary_operator primary_operand 

36238 are known as unary primaries. The primaries with three elements in either of the two forms: 

36239 primary_operand —primary_operator primary_operand 

36240 primary_operand primary_operator primary_operand 

36241 are known as binary primaries. Additional implementation-dependent operators and 

36242 primary operators may be provided by implementations. They shall be of the form -operator 

36243 where the first character of operator is not a digit. 

36244 The algorithm for determining the precedence of the operators and the return value that shall be 

36245 generated is based on the number of arguments presented to test. (However, when using the 

36246 form, the right-bracket final argument shall not be counted in this algorithm.) 

36247 In the following list, $1, $2, $3, and $4 represent the arguments presented to test: 

36248 0 arguments: Exit false (1). 

36249 1 argument: Exit true (0) if $1 is not null; otherwise, exit false. 

36250 2 arguments: • If $1 is ' ! ', exit true if $2 is null, false if $2 is not null. 
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36251 


• If $1 is a unary primary, exit true if the unary test is true, false if the unary 

36252 


test is false. 

36253 


• Otherwise, produce unspecified results. 

36254 

3 arguments: 

• If $2 is a binary primary, perform the binary test of $1 and $3. 

36255 


• If $1 is ' !', negate the two-argument test of $2 and $3. 

36256 MAN 


• If $1 is ' (' and $3 is ' ) ', perform the unary test of $2. 

36257 


• Otherwise, produce unspecified results. 

36258 

4 arguments: 

• If $1 is ' !', negate the three-argument test of $2, $3, and $4. 

36259 XSI 


• If $1 is ' (' and $4 is ' ) ', perform the two-argument test of $2 and $3. 

36260 


• Otherwise, the results are unspecified. 

36261 XSI 

>4 arguments: Combinations of primaries and operators shall be evaluated using the 

36262 


precedence and associativity rules described previously. In addition, the 

36263 

36264 


string comparison binary primaries ' =' and "! =" shall have a higher 
precedence than any unary primary. 

36265 STDIN 



36266 

Not used. 


36267 INPUT FILES 


36268 

None. 


36269 ENVIRONMENT VARIABLES 

36270 

The following environment variables shall affect the execution of test: 

36271 

LANG 

Provide a default value for the internationalization variables that are unset or null. 

36272 


If LANG is unset or null, the corresponding value from the implementation- 

36273 


dependent default locale shall be used. If any of the internationalization variables 

36274 


contains an invalid setting, the utility shall behave as if none of the variables had 

36275 


been defined. 

36276 

LC_ALL 

If set to a non-empty string value, override the values of all the other 

36277 


internationalization variables. 

36278 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 

36279 


characters (for example, single-byte as opposed to multi-byte characters in 

36280 


arguments). 

36281 

LC_MESSAGES 

36282 


Determine the locale that should be used to affect the format and contents of 

36283 


diagnostic messages written to standard error. 

36284 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

36285 ASYNCHRONOUS EVENTS 

36286 

Default. 


36287 STDOUT 


36288 

Not used. 


36289 STDERR 


36290 

Used only for diagnostic messages. 
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36291 OUTPUT FILES 

36292 None. 

36293 EXTENDED DESCRIPTION 

36294 None. 

36295 EXIT STATUS 

36296 The following exit values shall be returned: 

36297 0 expression evaluated to true. 

36298 1 expression evaluated to false or expression was missing. 

36299 >1 An error occurred. 

36300 CONSEQUENCES OF ERRORS 

36301 Default. 

36302 APPLICATION USAGE 

36303 Scripts should be careful when dealing with user-supplied input that could be confused with 

36304 primaries and operators. Unless the application writer knows all the cases that produce input to 

36305 the script, invocations like: 

36306 test "$1" -a "$2" 

36307 should be written as: 

36308 test "$1" && test "$2" 

36309 to avoid problems if a user supplied values such as $1 set to ' !' and $2 set to the null string. 

36310 That is, in cases where maximal portability is of concern, replace: 

36311 test exprl —a expr2 

36312 with: 

36313 test exprl && test expr2 

36314 and replace: 

36315 test exprl —o expr2 

36316 with: 

36317 test exprl | | test expr2 

36318 but note that, in test, -a has higher precedence than -o while "&&" and " | | " have equal 

36319 precedence in the shell. 

36320 Parentheses or braces can be used in the shell command language to effect grouping. 

36321 Parentheses must be escaped when using sir, for example: 

36322 test \ ( exprl —a expr2 \) —o expr3 

36323 This command is not always portable outside XSI-conformant systems. The following form can 

36324 be used instead: 

36325 ( test exprl && test expr2 ) | | test expr3 

36326 The two commands: 

36327 test "$1" 

36328 test ! "$1" 
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could not be used reliably on some historical systems. Unexpected results would occur if such a 
string expression were used and $1 expanded to ' !', ' (', or a known unary primary. Better 
constructs are: 

test -n "$1" 
test -z "$1" 

respectively. 

Historical systems have also been unreliable given the common construct: 

test "$response" = "expected string" 

One of the following is a more reliable form: 

test "X$response" = "Xexpected string" 
test "expected string" = "$response" 

Note that the second form assumes that expected string could not be confused with any unary 
primary. If expected string starts with ' , ' (', ' !', or even ' =', the first form should be used 

instead. Using the preceding rules without the marked extensions, any of the three comparison 
forms is reliable, given any input. (However, note that the strings are quoted in all cases.) 

Because the string comparison binary primaries, ' = ' and " ! =", have a higher precedence than 
any unary primary in the greater than 4 argument case, unexpected results can occur if 
arguments are not properly prepared. For example, in: 

test -d $1 —o —d $2 

If $1 evaluates to a possible directory name of ' =', the first three arguments are considered a 
string comparison, which shall cause a syntax error when the second -d is encountered. One of 
the following forms prevents this; the second is preferred: 

test \( -d "$1" \) -o \( -d "$2" \) 
test -d "$1" || test -d "$2" 

Also in the greater than 4 argument case: 

test "$1" = "bat" -a "$2" = "ball" 

Syntax errors occur if $1 evaluates to ' (' or ' !'. One of the following forms prevents this; the 
third is preferred: 

test "X$l" = "Xbat" -a "X$2" = "Xball" 
test "$1" = "bat" && test "$2" = "ball" 
test "X$l" = "Xbat" && test "X$2" = "Xball" 

EXAMPLES 

1. Exit if there are not two or three arguments (two variations): 

if [ $# —ne 2 —a $# —ne 3 ]; then exit 1; fi 

if [ $# —It 2 —o $# —gt 3 ]; then exit 1; fi 

2. Perform a mkdir if a directory does not exist: 
test ! —d tempdir && mkdir tempdir 

3. Wait for a file to become non-readable: 

while test —r thefile 
do 

sleep 30 
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36370 

36371 

36372 

36373 

36374 

36375 

36376 

36377 

36378 

36379 

36380 

36381 

36382 

36383 

36384 

36385 

36386 

36387 

36388 

36389 

36390 

36391 

36392 

36393 

36394 

36395 

36396 

36397 

36398 

36399 

36400 

36401 

36402 

36403 

36404 

36405 

36406 

36407 

36408 

36409 

36410 

36411 


done 

echo '"thefile" is no longer readable' 

4. Perform a command if the argument is one of three strings (two variations): 

if [ "$1" = "pear" ] | | [ "$1" = "grape" ] I I [ "$1" = "apple" ] 

then 

command 

fi 

case "$1" in 

pear|grape|apple) command ;; 

esac 


RATIONALE 

The KomShell-derived conditional command (double bracket [[ ]]) was removed from the shell 
command language description in an early proposal. Objections were raised that the real 
problem is misuse of the test command ([), and putting it into the shell is the wrong way to fix 
the problem. Instead, proper documentation and a new shell reserved word (!) are sufficient. 

Tests that require multiple test operations can be done at the shell level using individual 
invocations of the test command and shell logicals, rather than using the error-prone -o flag of 
test. 

XSI-conformant systems support more than four arguments. 

XSI-conformant systems support the combining of primaries with the following constructs: 

expressionl -a expression 2 

True if both expressionl and expression2 are true. 

expressionl -o expression2 

True if at least one of expressionl and expression 2 are true. 

( expression ) 

True if expression is true. 

In evaluating these more complex combined expressions, the following precedence rules are 
used: 

• The unary primaries have higher precedence than the algebraic binary primaries. 

• The unary primaries have lower precedence than the string binary primaries. 

• The unary and binary primaries have higher precedence than the unary string primary. 

• The ! operator has higher precedence than the -a operator, and the -a operator has higher 
precedence than the -o operator. 

• The -a and -o operators are left associative. 

• The parentheses can be used to alter the normal precedence and associativity. 

The BSD and System V versions of -f are not the same. The BSD definition was: 

-f file True if file exists and is not a directory. 

The SVID version (true if the file exists and is a regular file) was chosen for this volume of 
IEEE Std. 1003.1-200x because its use is consistent with the -b, -c, -d, and -p operands (file 
exists and is a specific file type). 

The -e primary, possessing similar functionality to that provided by the C shell, was added 
because it provides the only way for a shell script to find out if a file exists without trying to 
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open the file. Since implementations are allowed to add additional file types, a portable script 
cannot use: 

test —b foo —o —c foo —o -d foo —o —f foo —o —p foo 

to find out if foo is an existing file.) On historical BSD systems, the existence of a file could be 
determined by: 

test —f foo —o -d foo 

but there was no easy way to determine that an existing file was a regular file. An early proposal 
used the KomShell -a primary (with the same meaning), but this was changed to -e because 
there were concerns about the high probability of humans confusing the -a primary with the -a 
binary operator. 

The -a and -o binary operators and the grouping parentheses were omitted from this volume of 
IEEE Std. 1003.1-200x due to a difference between historical implementations of the test utility in 
the precedence of the binary primaries ' =' and "! =" compared to the unary primaries -b, -c, 
-d, -f, -g, -n, -p, -r, -s, -t, -u, -w, -x, and -z. On BSD, Version 7, PWB, and 32V systems, the 
unary primaries have higher precedence than the binary operators; on System III and System V 
implementations, the binary operators ' =' and "! =" have higher precedence. The change was 
apparently made for System III so that the construct: 

test "$1" = "$2" 

could be made to work even if $1 started with ' —'. This change was considered a mistake 
because: 

• It is not a complete solution; if $1 expands to ' (' or ' !', it still does not work. 

• It makes it impossible to use the unary primaries -n and -z to test for a null string if there is 
any chance that the string will expand to ' = '. 

• More importantly, there was the well known option of specifying: 
test X"$l" = X"$2" 

that always worked. 

Unfortunately, when the ' =' and " ! =" binary primaries were given precedence over the unary 
primaries, there was no solution provided for scripts that wanted to reliably specify something 
like: 

test —n "$1" 

because if $1 expands to ' =', it gives a syntax error. 

There was some discussion of forbidding the System V behavior and requiring the more logical 
precedence that originated in its predecessors and that remains in BSD-based systems. However, 
there are simply too many historical applications that would break if System V were required to 
make this change; this number dwarfed the number of scripts using combination logic that 
would then no longer be strictly portable. 

This volume of IEEE Std. 1003.1-200x requires that if test is called with one, two, three, or four 
operands it correctly interprets the expression even if there is an alternate syntax tree that could 
lead to a syntax error. It eliminates the requirement that many string comparisons be protected 
with leading characters, such as: 

test X"$l" = X"$ 2 " 

and allows the single-argument string form to be used with all possible inputs. 
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36454 The following examples show some of the changes that are required to be made to make 

36455 historical BSD and System V-based implementations of test conform to this volume of 

36456 IEEE Std. 1003.1-200x: 

36457 test —d = P OS IX. 2 True if there is a directory named =. 

36458 BSD True if there is a directory named =. 

36459 System V Syntax error; = needs two operands. 

36460 test —d = —f POSIX.2 False 

36461 BSD Syntax error; it expects -a or -o after -d =. 

36462 System V False 

36463 Implementations are prohibited from extending test with options because it would make the test 

36464 string case ambiguous for inputs that might match an extended option. Implementations can 

36465 add primaries and operators, as indicated. 

36466 The following options were not included in this volume of IEEE Std. 1003.1-200x, although they 

36467 are provided by some historical implementations, since these facilities and concepts are not 

36468 supported by the System Interfaces volume of IEEE Std. 1003.1-200x nor defined in this volume 

36469 of IEEE Std. 1003.1-200x. These operands should not be used by new implementations for other 

36470 purposes. 


36471 

-h file 

True if file exists and is a symbolic link. 

36472 

-k file 

True if file exists and its sticky bit is set. 

36473 

-Lfile 

True if file is a symbolic link. 

36474 

-Cfile 

True if file is a contiguous file. 

36475 

-Sfile 

True if file is a socket. 

36476 

-V file 

True if file is a version file. 

36477 

36478 

36479 

The following option was not included because it was undocumented in most implementations, 
has been removed from some implementations (including System V), and the functionality is 
provided by the shell (see Section 2.6.2 on page 51. 

36480 

-1 string 

The length of the string string. 


36481 The -b, -c, -g, -p, -u, and -x operands are derived from the SVID; historical BSD does not 

36482 provide them. The -k operand is derived from System V; historical BSD does not provide it. 

36483 On historical BSD systems, test -w directory always returned false because test tried to open the 

36484 directory for writing, which always fails. 

36485 Some additional primaries newly invented or from the KomShell appeared in an early proposal 

36486 as part of the conditional command ([[ ]]): si > s2, si < s2, str = pattern, str != pattern, fl -nt/2,/2 

36487 -ot/2, and/2 -ef/2. They were not carried forward into the test utility when the conditional 

36488 command was removed from the shell because they have not been included in the test utility 

36489 built into historical implementations of the sh utility. 

36490 The -t file_descriptor primary is shown with a mandatory argument because the grammar is 

36491 ambiguous if it can be omitted. Historical implementations have allowed it to be omitted, 

36492 providing a default of 1. 

36493 FUTURE DIRECTIONS 

36494 None. 
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36495 SEE ALSO 

36496 find 

36497 CHANGE HISTORY 

36498 First released in Issue 2. 

36499 Issue 4 

36500 Aligned with the ISO/IEC 9945-2:1993 standard. 

36501 Issue 5 

36502 FUTURE DIRECTIONS section added. I 

36503 Issue 6 I 

36504 The -h operand is added for symbolic links, and access permission requirements are clarified for I 

36505 the -r, -w, and -x operands to align with the IEEE P1003.2b draft standard. I 

36506 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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36508 

36509 

36510 

36511 

36512 

36513 

36514 

36515 

36516 

36517 

36518 

36519 

36520 

36521 

36522 

36523 

36524 

36525 

36526 

36527 

36528 

36529 

36530 

36531 

36532 

36533 

36534 

36535 

36536 

36537 

36538 

36539 

36540 

36541 

36542 

36543 

36544 

36545 

36546 


NAME 

time — time a simple command 

SYNOPSIS 

UP time [—p] utility [argument...] 

DESCRIPTION 

The time utility shall invoke the utility named by the utility operand with arguments supplied as 
the argument operands and write a message to standard error that lists timing statistics for the 
utility. The message shall include the following information: 

• The elapsed (real) time between invocation of utility and its termination. 

• The User CPU time, equivalent to the sum of the tms_utime and tms_cutime fields returned by 
the times () function defined in the System Interfaces volume of IEEE Std. 1003.1-200x for the 
process in which utility is executed. 

• The System CPU time, equivalent to the sum of the tms_stime and tms_cstime fields returned 
by the times () function for the process in which utility is executed. 

The precision of the timing shall be no less than the granularity defined for the size of the clock 
tick unit on the system, but the results shall be reported in terms of standard time units (for 
example, 0.02 seconds, 00:00:00.02, lm33.75s, 365.21 seconds), not numbers of clock ticks. 

When time is used as part of a pipeline, the times reported are unspecified, except when it is the 
sole command within a grouping command (see Section 2.9.4.1 on page 75) in that pipeline. For 
example, the commands on the left are unspecified; those on the right report on utilities a and c, 
respectively: 

time a | b | c { time a } | b I c 

a I b | time c a | b | (time c) 

OPTIONS 

The time utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following option shall be supported: 

-p Write the timing output to standard error in the format shown in the STDERR 

section. 

OPERANDS 

The following operands shall be supported: 

utility The name of a utility that is to be invoked. If the utility operand names any of the 

special built-in utilities in Section 2.14 on page 96, the results are undefined. 

argument Any string to be supplied as an argument when invoking the utility named by the 
utility operand. 

STDIN 

Not used. 

INPUT FILES 

None. 
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36547 ENVIRONMENT VARIABLES 


36548 

The following environment variables shall affect the execution of time : 

36549 

36550 

36551 

36552 

36553 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

36554 

36555 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

36556 

36557 

36558 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

36559 

36560 

36561 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic and informative messages written to standard error. 

36562 

36563 

LCJNUMERIC 

Determine the locale for numeric formatting. 

36564 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 

36565 

36566 

36567 

PATH 

Determine the search path that shall be used to locate the utility to be invoked; see 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, 
Environment Variables. 


36568 ASYNCHRONOUS EVENTS 

36569 Default. 

36570 STDOUT 

36571 Not used. 

36572 STDERR 

36573 The standard error shall be used to write the timing statistics. If -p is specified, the following 

36574 format shall be used in the POSIX locale: 

36575 "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>, 

36576 <system seconds> 

36577 where each floating-point number shall be expressed in seconds. The precision used may be less 

36578 than the default six digits of %/, but shall be sufficiently precise to accommodate the size of the 

36579 clock tick on the system (for example, if there were 60 clock ticks per second, at least two digits 

36580 shall follow the radix character). The number of digits following the radix character shall be no 

36581 less than one, even if this always results in a trailing zero. The implementation may append 

36582 white space and additional information following the format shown here. 

36583 OUTPUT FILES 

36584 None. 

36585 EXTENDED DESCRIPTION 

36586 None. 

36587 EXIT STATUS 

36588 If the utility utility is invoked, the exit status of time shall be the exit status of utility; otherwise, 

36589 the time utility shall exit with one of the following values: 
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36590 

36591 

36592 

36593 

36594 

36595 

36596 

36597 

36598 

36599 

36600 

36601 

36602 

36603 

36604 

36605 

36606 

36607 

36608 

36609 

36610 

36611 

36612 

36613 

36614 

36615 

36616 

36617 

36618 

36619 

36620 

36621 

36622 

36623 

36624 

36625 

36626 

36627 

36628 

36629 

36630 

36631 

36632 

36633 

36634 


1-125 An error occurred in the time utility. 

126 The utility specified by utility was found but could not be invoked. 

127 The utility specified by utility could not be found. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The command, env, nice, nohnp, time, and xargs utilities have been specified to use exit code 127 if 
an error occurs so that applications can distinguish "failure to find a utility" from "invoked 
utility exited with an error indication". The value 127 was chosen because it is not commonly 
used for other meanings; most utilities use small values for "normal error conditions" and the 
values above 128 can be confused with termination due to receipt of a signal. The value 126 was 
chosen in a similar manner to indicate that the utility could be found, but not invoked. Some 
scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction 
between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 
exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 
any other reason. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

It is frequently desirable to apply time to pipelines or lists of commands. This can be done by 
placing pipelines and command lists in a single file; this file can then be invoked as a utility, and 
the time applies to everything in the file. 

Alternatively, the following command can be used to apply time to a complex command: 
time sh —c 'complex-command-line' 

RATIONALE 

The time utility when originally proposed for this volume of IEEE Std. 1003.1-200x, was rejected 
because it was not useful for portable applications: 

• The underlying CPU definitions from the System Interfaces volume of IEEE Std. 1003.1-200x 
are vague, so the numeric output could not be compared accurately between systems or even 
between invocations. 

• The creation of portable benchmark programs was outside the scope this volume of 
IEEE Std. 1003.1-200x. 

However, time does fit in the scope of user portability. Human judgement can be applied to the 
analysis of the output, and it could be very useful in hands-on debugging of applications or in 
providing subjective measures of system performance. Hence it has been included in this 
volume of IEEE Std. 1003.1-200x. 

The default output format has been left unspecified because historical implementations differ 
greatly in their style of depicting this numeric output. The -p option was invented to provide 
scripts a common means of obtaining this information. 

In the KomShell, time is a shell reserved word that can be used to time an entire pipeline, rather 
than just a simple command. The POSIX definition has been worded to allow this 
implementation. Consideration was given to invalidating this approach because of the historical 
model from the C shell and System V shell. However, since the System V time utility historically 
has not produced accurate results in pipeline timing (because the constituent processes are not 
all owned by the same parent process, as allowed by POSIX), it did not seem worthwhile to 
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36635 

36636 

36637 

36638 

36639 

36640 

36641 

36642 

36643 

36644 

36645 

36646 

36647 

36648 


break historical KomShell usage. 

The term utility is used, rather than command, to highlight the fact that shell compound 
commands, pipelines, special built-ins, and so on, cannot be used directly. However, utility 
includes user application programs and shell scripts, not just the standard utilities. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

sh, the System Interfaces volume of IEEE Std. 1003.1-200x, times () 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 
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36649 NAME 

36650 touch — change file access and modification times 

36651 SYNOPSIS 

36652 touch [—acm] [ —r ref_file\ —t time ] file. . . 


36653 DESCRIPTION 

36654 The touch utility shall change the modification times, access times, or both of files. The 

36655 modification time shall be equivalent to the value of the st_mtime member of the stat structure 

36656 for a file, as described in the System Interfaces volume of IEEE Std. 1003.1-200x; the access time 

36657 shall be equivalent to the value of st_atime. 

36658 The time used can be specified by the -t time option-argument, the corresponding time fields of 

36659 the file referenced by the -r refjile option-argument, or the date_time operand, as specified in the 

36660 following sections. If none of these are specified, touch shall use the current time (the value 

36661 returned by the equivalent of the time () function defined in the System Interfaces volume of 

36662 IEEE Std. 1003.1-200x). 


36663 For each file operand, touch shall perform actions equivalent to the following functions defined 

36664 in the System Interfaces volume of IEEE Std. 1003.1-200x: 


36665 

36666 

36667 


1 . If file does not exist, a creat() function call is made with the file operand used as the path 
argument and the value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, 
S_IWGRP, S_IROTH, and S_IWOTH used as the mode argument. 


36668 


2. The utime () function is called with the following arguments: 


36669 


a. The file operand is used as the path argument. 


36670 

36671 


b. The utimbuf structure members actime and modtime are determined as described in 
the OPTIONS section. 


36672 OPTIONS 

36673 The touch utility shall conform to the System Interface Definitions volume of I 

36674 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 


36675 

36676 

36677 

36678 

36679 

36680 

36681 

36682 

36683 


The following options shall be supported: 


-a 


-c 


-m 


-r refjile 


Change the access time of file. Do not change the modification time unless -m is 
also specified. 

Do not create a specified file if it does not exist. Do not write any diagnostic 
messages concerning this condition. 

Change the modification time of file. Do not change the access time unless -a is 
also specified. 

Use the corresponding time of the file named by the path name refjile instead of 
the current time. 


36684 -t time Use the specified time instead of the current time. The option-argument shall be a 

36685 decimal number of the form: 


36686 

36687 

36688 

36689 


[[CC] YY]MMDDhhmm [. SS] 

where each two digits represents the following: 
MM The month of the year [01-12]. 

DD The day of the month [01-31]. 
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36690 

hh 

The 

36691 

mm 

The 

36692 

CC 

The 

36693 

YY 

The 

36694 

SS 

The 


hour of the day [00-23]. 

minute of the hour [00-59]. 

first two digits of the year (the century). 

second two digits of the year. 

second of the minute [00-61]. 


36695 Both CC and YY shall be optional. If neither is given, the current year shall be 

36696 assumed. If YY is specified, but CC is not, CC shall be derived as follows: 

36697 

36698 

36699 


If YY is: 

CC becomes: 

69-99 

19 

00-68 

20 


36700 

36701 

36702 

36703 MAN 

36704 

36705 


The resulting time shall be affected by the value of the TZ environment variable. If 
the resulting time value precedes the Epoch, touch shall exit immediately with an 
error status. The range of valid times past the Epoch is implementation-dependent, 
but it shall extend to at least the time 0 hours, 0 minutes, 0 seconds, January 1, 
2038, Coordinated Universal Time. Some systems may not be able to represent 
dates beyond the January 18,2038, because they use signed int as a time holder. 


36706 

36707 

36708 

36709 


The range for SS is (00-61) rather than (00-59) because of leap seconds. If SS is 60 or 
61, and the resulting time, as affected by the TZ environment variable, does not 
refer to a leap second, the resulting time shall be one or two seconds after a time 
where SS is 59. If SS is not given a value, it is assumed to be zero. 


36710 If neither the -a nor -m options were specified, touch shall behave as if both the -a and -m 

36711 options were specified. 


36712 OPERANDS 

36713 The following operands shall be supported: 

36714 file A path name of a file whose times shall be modified. 


36715 STDIN 

36716 Not used. 


36717 INPUT FILES 

36718 None. 


36719 ENVIRONMENT VARIABLES 

36720 The following environment variables shall affect the execution of touch: 


36721 

36722 

36723 

36724 

36725 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


36726 

36727 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


36728 

36729 

36730 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


36731 LC_MESSAGES 

36732 Determine the locale that should be used to affect the format and contents of 
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36733 

36734 

36735 

36736 

36737 

36738 

36739 

36740 

36741 

36742 

36743 

36744 

36745 

36746 

36747 

36748 

36749 

36750 

36751 

36752 

36753 

36754 

36755 

36756 

36757 

36758 

36759 

36760 

36761 

36762 

36763 

36764 

36765 

36766 

36767 

36768 

36769 

36770 

36771 

36772 


diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

TZ Determine the timezone to be used for interpreting the time option-argument. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The utility executed successfully and all requested changes were made. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The interpretation of time is taken to be seconds since the Epoch (see the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Section 3.342, Seconds Since the Epoch). It should I 
be noted that implementations conforming to the System Interfaces volume of I 
IEEE Std. 1003.1-200x do not take leap seconds into account when computing seconds since the 
Epoch. When SS=60 is used, the resulting time always refers to 1 plus seconds since the Epoch for a 
time when SS=59. 

Although the -t time option-argument and the obsolescent date_time operand specify values in 
1969, the access time and modification time fields are defined in terms of seconds since the 
Epoch (midnight on 1 January 1970 UTC). Therefore, depending on the value of TZ when touch is 
run, there is never more than a few valid hours in 1969 and there need not be any valid times in 
1969. 

One ambiguous situation occurs if -t time is not specified, -r refjile is not specified, and the first 
operand is an eight or ten-digit decimal number. A portable script can avoid this problem by 
using: 

touch — file 

or: 

touch ./file 
in this case. 

EXAMPLES 

None. 
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36773 RATIONALE 

36774 The functionality of touch is described almost entirely through references to functions in the 

36775 System Interfaces volume of IEEE Std. 1003.1-200x. In this way, there is no duplication of effort 

36776 required for describing such side effects as the relationship of user IDs to the user database, 

36777 permissions, and so on. 

36778 There are some significant differences between the touch utility in this volume of 

36779 IEEE Std. 1003.1-200x and those in System V and BSD systems. They are upward-compatible for 

36780 historical applications from both implementations: 

36781 1. In System V, an ambiguity exists when a path name that is a decimal number leads the 

36782 operands; it is treated as a time value. In BSD, no time value is allowed; files may only be 

36783 touched to the current time. The -t time construct solves these problems for future portable 

36784 applications (note that the -t option is not historical practice). 

36785 2. The inclusion of the century digits, CC, is also new. Note that a ten-digit time value is 

36786 treated as if YY, and not CC, were specified. The caveat about the range of dates following 

36787 the Epoch was included as recognition that some implementations are not able to 

36788 represent dates beyond 18 January 2038 because they use signed int as a time holder. 

36789 The -r option was added because several comments requested this capability. This option was 

36790 named -f in an early proposal, but was changed because the -f option is used in the BSD version 

36791 of touch with a different meaning. 

36792 At least one historical implementation of touch incremented the exit code if -c was specified and 

36793 the file did not exist. This volume of IEEE Std. 1003.1-200x requires exit status zero if no errors 

36794 occur. 

36795 FUTURE DIRECTIONS 

36796 Applications should use the -r or -t options. 

36797 SEE ALSO 

36798 date, the System Interfaces volume of IEEE Std. 1003.1-200x, creat( ), time( ), <sys/stat.h> 

36799 CHANGE HISTORY 

36800 First released in Issue 2. 

36801 Issue 4 

36802 Aligned with the ISO/IEC 9945-2:1993 standard. 

36803 Issue 6 

36804 The obsolescent date_time operand is removed. 

36805 The Open Group corrigenda item U027/1 has been applied. This extends the range of valid time 

36806 past the Epoch to at least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated 

36807 Universal Time. This is a new requirement on POSIX implementations. 

36808 Notes to Reviewers 

36809 This section with side shading will not appear in the final copy. - Ed. 

36810 Should leap seconds be 00-61? c9x infers that it is only 00-60, and astronomers confirm that 

36811 double leap seconds do not occur. 
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36812 NAME 

36813 tput — change terminal characteristics 

36814 SYNOPSIS 

36815 UP tput [-T type] operand. . . 

36816 


36817 DESCRIPTION 

36818 The tput utility shall display terminal-dependent information. The manner in which this 

36819 information is retrieved is unspecified. The information displayed shall clear the terminal screen, 

36820 initialize the user's terminal, or reset the useds terminal, depending on the operand given. The 

36821 exact consequences of displaying this information are unspecified. 


36822 OPTIONS 

36823 The tput utility shall conform to the System Interface Definitions volume of I 

36824 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

36825 The following option shall be supported: 

36826 -T type Indicate the type of terminal. If this option is not supplied and the TERM variable 

36827 is unset or null, an unspecified default terminal type shall be used. The setting of 

36828 type shall take precedence over the value in TERM. 


36829 OPERANDS 

36830 The following strings shall be supported as operands by the implementation in the POSIX locale: 


36831 


clear Display the clear-screen sequence. 


36832 init Display the sequence that initializes the user's terminal in an implementation- 

36833 dependent manner. 


36834 reset Display the sequence that resets the user's terminal in an implementation- 

36835 dependent manner. 


36836 If a terminal does not support any of the operations described by these operands, this shall not 

36837 be considered an error condition. 


36838 STDIN 

36839 Not used. 


36840 INPUT FILES 

36841 None. 


36842 ENVIRONMENT VARIABLES 

36843 The following environment variables shall affect the execution of tput: 


36844 

36845 

36846 

36847 

36848 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


36849 LC_AEL If set to a non-empty string value, override the values of all the other 

36850 internationalization variables. 


36851 

36852 

36853 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


36854 LC_MESSAGES 

36855 Determine the locale that should be used to affect the format and contents of 
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36861 

36862 

36863 

36864 

36865 

36866 

36867 

36868 

36869 

36870 

36871 

36872 

36873 

36874 

36875 

36876 

36877 

36878 

36879 

36880 

36881 

36882 

36883 

36884 

36885 

36886 

36887 

36888 

36889 

36890 

36891 

36892 

36893 

36894 


tput 


Utilities 


diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

TERM Determine the terminal type. If this variable is unset or null, and if the -T option is 

not specified, an unspecified default terminal type shall be used. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

If standard output is a terminal device, it may be used for writing the appropriate sequence to 
clear the screen or reset or initialize the terminal. If standard output is not a terminal device, 
undefined results occur. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 The requested string was written successfully. 

1 Unspecified. 

2 Usage error. 

3 No information is available about the specified terminal type. 

4 The specified operand is invalid. 

>4 An error occurred. 

CONSEQUENCES OF ERRORS 

If one of the operands is not available for the terminal, tput continues processing the remaining 
operands. 

APPLICATION USAGE 

The difference between resetting and initializing a terminal is left unspecified, as they vary 
greatly based on hardware types. In general, resetting is a more severe action. 

Some terminals use control characters to perform the stated functions, and on such terminals it 
might make sense to use tput to store the initialization strings in a file or environment variable 
for later use. However, because other terminals might rely on system calls to do this work, the 
standard output cannot be used in a portable manner, such as the following non-portable 
constructs: 

ClearVar= 'tput clear ' 

tput reset | mailx —s "Wake Up" ddg 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 
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36905 
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EXAMPLES 

1. Initialize the terminal according to the type of terminal in the environmental variable 
TERM. This command can be included in a .profile file. 

tput init 

2. Reset a 450 terminal. 

tput -T 450 reset 

RATIONALE 

The list of operands was reduced to a minimum for the following reasons: 

• The only features chosen were those that were likely to be used by human users interacting 
with a terminal. 

• Specifying the full terminfo set was not considered desirable, but the standard developers did 
not want to select among operands. 

• This volume of IEEE Std. 1003.1-200x does not attempt to provide applications with 
sophisticated terminal handling capabilities, as that falls outside of its assigned scope and 
intersects with the responsibilities of other standards bodies. 

The difference between resetting and initializing a terminal is left unspecified as this varies 
greatly based on hardware types. In general, resetting is a more severe action. 

The exit status of 1 is historically reserved for finding out if a Boolean operand is not set. 
Although the operands were reduced to a minimum, the exit status of 1 should still be reserved 
for the Boolean operands, for those sites that wish to support them. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

stty, tabs 

CHANGE HISTORY 

First released in Issue 4. 


Issue 6 

This utility is now marked as part of the User Portability Utilities option. 
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36923 NAME 

36924 tr — translate characters 


36925 SYNOPSIS 

36926 tr [—c | —C] [—s ] stringl string2 

36927 tr — s [—c I — C] stringl 

36928 tr — d [—c I — C] stringl 

36929 tr — ds [—c I — C] stringl string2 

36930 DESCRIPTION 

36931 The tr utility shall copy the standard input to the standard output with substitution or deletion 

36932 of selected characters. The options specified and the stringl and stringl operands shall control 

36933 translations that occur while copying characters and single-character collating elements. 


36934 OPTIONS 

36935 The tr utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

36936 Section 12.2, Utility Syntax Guidelines. I 

36937 The following options shall be supported: 


36938 

-c 

36939 


36940 

-C 

36941 



Complement the set of values specified by stringl. See the EXTENDED I 
DESCRIPTION section. I 

Complement the set of characters specified by stringl. See the EXTENDED I 
DESCRIPTION section. 


36942 -d 


Delete all occurrences of input characters that are specified by stringl. 


36943 -S 

36944 


Replace instances of repeated characters with a single character, as described in the 
EXTENDED DESCRIPTION section. 


36945 OPERANDS 

36946 The following operands shall be supported: 

36947 stringl, string2 

36948 Translation control strings. Each string shall represent a set of characters to be 

36949 converted into an array of characters used for the translation. For a detailed 

36950 description of how the strings are interpreted, see the EXTENDED DESCRIPTION 

36951 section. 


36952 STDIN 

36953 The standard input can be any type of file. 

36954 INPUT FILES 

36955 None. 


36956 ENVIRONMENT VARIABLES 

36957 The following environment variables shall affect the execution of tr: 


36958 

36959 

36960 

36961 

36962 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


36963 

36964 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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36965 LC_COLLATE 

36966 Determine the locale for the behavior of range expressions and equivalence classes. 

36967 LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

36968 characters (for example, single-byte as opposed to multi-byte characters in 

36969 arguments) and the behavior of character classes. 

36970 LC_MESSAGES 

36971 Determine the locale that should be used to affect the format and contents of 

36972 diagnostic messages written to standard error. 

36973 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

36974 ASYNCHRONOUS EVENTS 

36975 Default. 

36976 STDOUT 

36977 The tr output shall be identical to the input, with the exception of the specified transformations. 

36978 STDERR 

36979 Used only for diagnostic messages. 

36980 OUTPUT FILES 

36981 None. 


36982 EXTENDED DESCRIPTION 

36983 The operands stringl and string 2 (if specified) define two arrays of characters. The constructs in 

36984 the following list can be used to specify characters or single-character collating elements. If any 

36985 of the constructs result in multi-character collating elements, tr shall exclude, without a 

36986 diagnostic, those multi-character elements from the resulting array. 


36987 


character Any character not described by one of the conventions below represents itself. 


36988 

36989 

36990 

36991 

36992 

36993 

36994 

36995 


\octal Octal sequences can be used to represent characters with specific coded values. An 

octal sequence shall consist of a backslash followed by the longest sequence of one, 
two, or three-octal-digit characters (01234567). The sequence shall cause the value I 
whose encoding is represented by the one, two, or three-digit octal integer to be I 
placed into the array. If the size of a byte on the system is greater than nine bits, the 
valid escape sequence used to represent a byte is implementation-dependent. 
Multi-byte characters require multiple, concatenated escape sequences of this type, 
including the leading ' \' for each byte. 


36996 

36997 

36998 

36999 

37000 


\character The backslash-escape sequences in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Table 5-1, Escape Sequences and Associated Actions (' W, I 
' \a', ' \b', ' \f', ' \n' , ' \r', ' \t' , ' \v' ) shall be supported. The results of 
using any other character, other than an octal digit, following the backslash are 
unspecified. 


37001 C-C 

37002 

37003 

37004 

37005 

37006 


Represents the range of collating elements between the range endpoints (as long as 
neither endpoint is an octal sequence of the form \octal), inclusive, as defined by 
the current setting of the LC_COLLATE locale category. The application shall 
ensure that the starting endpoint precedes the second endpoint in the current 
collation order. The characters or collating elements in the range shall be placed in 
the array in ascending collation sequence. 


37007 

37008 

37009 


If either or both of the range endpoints are octal sequences of the form \octal , this 
shall represent the range of specific coded values between the two range 
endpoints, inclusive. 
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37010 

37011 

37012 

37013 

37014 

37015 

37016 

37017 

37018 

37019 

37020 

37021 

37022 

37023 

37024 

37025 

37026 

37027 

37028 

37029 

37030 

37031 

37032 

37033 

37034 

37035 

37036 

37037 

37038 

37039 

37040 

37041 

37042 

37043 

37044 

37045 

37046 

37047 

37048 

37049 

37050 

37051 

37052 

37053 

37054 

37055 


tr Utilities 


[:cZass:] Represents all characters belonging to the defined character class, as defined by the 
current setting of the LC_CTYPE locale category. The following character class 
names shall be accepted when specified in stringl: 

alnum blank digit lower punct upper 

alpha cntrl graph print space xdigit 

xsi In addition, character class expressions of the form [: name :] shall be recognized in 

those locales where the name keyword has been given a charclass definition in the 
LC_CTYPE category. 

When both the -d and -s options are specified, any of the character class names 
shall be accepted in stringl . Otherwise, only character class names lower or upper 
are valid in string2 and then only if the corresponding character class (upper and 
lower, respectively) is specified in the same relative position in stringl. Such a 
specification shall be interpreted as a request for case conversion. When [: lozver:] 
appears in stringl and [nipper:] appears in string2, the arrays shall contain the 
characters from the toupper mapping in the LCJCTYPE category of the current 
locale. When [:npper:\ appears in stringl and [dower :] appears in string2, the arrays 
shall contain the characters from the tolower mapping in the LCJCTYPE category 
of the current locale. The first character from each mapping pair shall be in the 
array for stringl and the second character from each mapping pair shall be in the 
array for string2 in the same relative position. 

Except for case conversion, the characters specified by a character class expression 
shall be placed in the array in an unspecified order. 

If the name specified for class does not define a valid character class in the current 
locale, the behavior is undefined. 

[=equiv=] Represents all characters or collating elements belonging to the same equivalence 
class as eqniv, as defined by the current setting of the LCJCOLLATE locale 
category. An equivalence class expression shall be allowed only in stringl, or in 
string2 when it is being used by the combined -d and -s options. The characters 
belonging to the equivalence class shall be placed in the array in an unspecified 
order. 

[x*n] Represents n repeated occurrences of the character x. Because this expression is 

used to map multiple characters to one, it is only valid when it occurs in string2. If 
n is omitted or is zero, it shall be interpreted as large enough to extend the string2- 
based sequence to the length of the stringl -based sequence. If n has a leading zero, 
it shall be interpreted as an octal value. Otherwise, it shall be interpreted as a 
decimal value. 

When the -d option is not specified: 

• Each input character found in the array specified by stringl shall be replaced by the character 
in the same relative position in the array specified by string2. When the array specified by 
string2 is shorter that the one specified by stringl , the results are unspecified. 

• If the -C option is specified, the complements of the characters specified by stringl (the set of I 
all characters in the current character set, as defined by the current setting of LCJCTYPE, 
except for those actually specified in the stringl operand) shall be placed in the array in 
ascending collation sequence, as defined by the current setting of LCJCOLLATE. 

• If the -c option is specified, the complement of the values specified by stringl shall be placed I 

in the array in ascending order by binary value. I 
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37056 • Because the order in which characters specified by character class expressions or equivalence I 

37057 class expressions is undefined, such expressions should only be used if the intent is to map 

37058 several characters into one. An exception is case conversion, as described previously. 

37059 When the -d option is specified: 

37060 • Input characters found in the array specified by stringl shall be deleted. 

37061 • When the -C option is specified with -d, all characters except those specified by stringl shall I 

37062 be deleted. The contents of stringl are ignored, unless the -s option is also specified. 

37063 • When the -c option is specified with -d, all values except those specified by stringl shall be I 

37064 deleted. The contents of stringl shall be ignored, unless the -s option is also specified. I 

37065 • The same string cannot be used for both the -d and the -s option; when both options are I 

37066 specified, both stringl (used for deletion) and s tringl (used for squeezing) shall be required. 

37067 When the -s option is specified, after any deletions or translations have taken place, repeated 

37068 sequences of the same character shall be replaced by one occurrence of the same character, if the 

37069 character is found in the array specified by the last operand. If the last operand contains a 

37070 character class, such as the following example: 

37071 tr —s ' [ : space : ] ' 

37072 the last operand's array shall contain all of the characters in that character class. However, in a 

37073 case conversion, as described previously, such as: 

37074 tr —s ' [ : upper : ] ' ' [ : lower : ] ' 

37075 the last operand's array shall contain only those characters defined as the second characters in 

37076 each of the toupper or tolower character pairs, as appropriate. 

37077 An empty string used for stringl or stringl produces undefined results. 

37078 EXIT STATUS 

37079 The following exit values shall be returned: 

37080 0 All input was processed successfully. 

37081 >0 An error occurred. 

37082 CONSEQUENCES OF ERRORS 

37083 Default. 

37084 APPLICATION USAGE 

37085 If necessary, stringl and stringl can be quoted to avoid pattern matching by the shell. 

37086 If an ordinary digit (representing itself) is to follow an octal sequence, the octal sequence must 

37087 use the full three digits to avoid ambiguity. 

37088 When stringl is shorter than stringl , a difference results between historical System V and BSD 

37089 systems. A BSD system pads stringl with the last character found in stringl. Thus, it is possible 

37090 to do the following: 

37091 tr 0123456789 d 

37092 which would translate all digits to the letter ' d' . Since this area is specifically unspecified in 

37093 this volume of IEEE Std. 1003.1-200x, both the BSD and System V behaviors are allowed, but a 

37094 portable application cannot rely on the BSD behavior. It would have to code the example in the 

37095 following way: 

37096 tr 0123456789 ' [d* ] ' 
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It should be noted that, despite similarities in appearance, the string operands used by tr are not 
regular expressions. 

Unlike some historical implementations, this definition of the tr utility correctly processes NUL 
characters in its input stream. NUL characters can be stripped by using: 

tr -d '\000' 

EXAMPLES 

1. The following example creates a list of all words in filel one per line in file2, where a word 
is taken to be a maximal string of letters. 

tr —cs "[:alpha:]" "[\n*]" <filel >file2 

2. The next example translates all lowercase characters in filel to uppercase and writes the 
results to standard output. 

tr "[:lower:]" "[:upper:]" <filel 

Note that the caveat expressed in the corresponding Issue 3 example is no longer in effect. 
This case conversion is now a special case that employs the tolower and toupper 
classifications, ensuring that proper mapping is accomplished (when the locale is correctly 
defined). 

3. This example uses an equivalence class to identify accented variants of the base character 
' e' in filel, which are stripped of diacritical marks and written to file2. 

tr "[=e=]" e <filel >file2 

RATIONALE 

In some early proposals, an explicit option -n was added to disable the historical behavior of 
stripping NUL characters from the input. It was considered that automatically stripping NUL 
characters from the input was not correct functionality. However, the removal of -n in a later 
proposal does not remove the requirement that tr correctly process NUL characters in its input 
stream. NUL characters can be stripped by using tr -d '\000'. 

Historical implementations of tr differ widely in syntax and behavior. For example, the BSD 
version has not needed the bracket characters for the repetition sequence. The POSIX Shell and 
Utilities tr syntax is based more closely on the System V and XPG3 model while attempting to 
accommodate historical BSD implementations. In the case of the short string2 padding, the 
decision was to unspecify the behavior and preserve System V and XPG3 scripts, which might 
find difficulty with the BSD method. The assumption was made that BSD users of tr have to 
make accommodations to meet the POSIX Shell and Utilities syntax. Since it is possible to use 
the repetition sequence to duplicate the desired behavior, whereas there is no simple way to 
achieve the System V method, this was the correct, if not desirable, approach. 

The use of octal values to specify control characters, while having historical precedents, is not 
portable. The introduction of escape sequences for control characters should provide the 
necessary portability. It is recognized that this may cause some historical scripts to break. 

An early proposal included support for multi-character collating elements. It was pointed out 
that, while tr does employ some syntactical elements from REs, the aim of tr is quite different; 
ranges, for example, do not have a similar meaning ("any of the chars in the range matches", 
versus "translate each character in the range to the output counterpart"). As a result, the 
previously included support for multi-character collating elements has been removed. What 
remains are ranges in current collation order (to support, for example, accented characters), 
character classes, and equivalence classes. 
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37141 In XPG3 the [-.class :] and [=equiv=] conventions are shown with double brackets, as in RE syntax. 

37142 However, tr does not implement RE principles; it just borrows part of the syntax. Consequently, 

37143 [-.class:] and [=equiv=] should be regarded as syntactical elements on a par with [x*n], which is 

37144 not an RE bracket expression. 

37145 The standard developers will consider changes to tr that allow it to translate characters between 

37146 different character encodings, or they will consider providing a new utility to accomplish this. 

37147 On historical System V systems, a range expression requires enclosing square-brackets, such as: 

37148 tr ' [a-z] ' ' [A-Z] ' 

37149 However, BSD-based systems did not require the brackets, and this convention is used by POSIX 

37150 Shell and Utilities to avoid breaking large numbers of BSD scripts: 

37151 tr a-z A-Z 

37152 The preceding System V script will continue to work because the brackets, treated as regular 

37153 characters, are translated to themselves. However, any System V script that relied on a-z 

37154 representing the three characters ' ' and ' z ' have to be rewritten as az—. I 

37155 A prior version of IEEE Std. 1003.1-200x had a -c option that behaved similarly to the -C option, I 

37156 but did not supply functionality equivalent to the -c option specified in IEEE Std. 1003.1-200x. I 

37157 This meant that historical practice of being able to specify tr -d\200-\377 (which would delete I 

37158 all bytes with the top bit set) would have no effect because, in the C locale, bytes with the values I 

37159 octal 200 to octal 377 are not characters. I 

37160 The earlier version also said that octal sequences referred to collating elements and could be I 

37161 placed adjacent to each other to specify multi-byte characters. However, it was noted that this I 

37162 caused ambiguities because tr would not be able to tell whether adjacent octal sequences were I 

37163 intending to specify multi-byte characters or multiple single byte characters. I 

37164 IEEE Std. 1003.1-200x specifies that octal sequences always refer to single byte binary values. I 

37165 FUTURE DIRECTIONS 

37166 None. 

37167 SEE ALSO 

37168 sect 

37169 CHANGE HISTORY 

37170 First released in Issue 2. 

37171 Issue 4 

37172 Aligned with the ISO/IEC 9945-2:1993 standard. I 

37173 Issue 6 I 

37174 The -C operand is added, and the description of the -c operand is changed to align with the I 

37175 IEEE P1003.2b draft standard. I 

37176 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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37177 NAME 

37178 true — return true value 

37179 SYNOPSIS 

37180 true 

37181 DESCRIPTION 

37182 The true utility shall return with exit code zero. 

37183 OPTIONS 

37184 None. 

37185 OPERANDS 

37186 None. 

37187 STDIN 

37188 Not used. 

37189 INPUT FILES 

37190 None. 

37191 ENVIRONMENT VARIABLES 

37192 None. 

37193 ASYNCHRONOUS EVENTS 

37194 Default. 

37195 STDOUT 

37196 Not used. 

37197 STDERR 

37198 None. 

37199 OUTPUT FILES 

37200 None. 

37201 EXTENDED DESCRIPTION 

37202 None. 

37203 EXIT STATUS 

37204 Default. 

37205 CONSEQUENCES OF ERRORS 

37206 None. 

37207 APPLICATION USAGE 

37208 This utility is typically used in shell scripts, as shown in the EXAMPLES section. The special 

37209 built-in utility: is sometimes more efficient than true. 

37210 EXAMPLES 

37211 This command is executed forever: 

37212 while true 

37213 do 

37214 command 

37215 done 
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37216 RATIONALE 

37217 The true utility has been retained in this volume of IEEE Std. 1003.1-200x, even though the shell 

37218 special built-in : provides similar functionality, because true is widely used in historical scripts 

37219 and is less cryptic to novice script readers. 

37220 FUTURE DIRECTIONS 

37221 None. 

37222 SEE ALSO 

37223 false, Section 2.9 on page 67 

37224 CHANGE HISTORY 

37225 First released in Issue 2. 

37226 Issue 4 

37227 Aligned with the ISO/IEC 9945-2:1993 standard. 
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37228 NAME 

37229 tsort — topological sort 

37230 SYNOPSIS 

37231 xsi tsort [file] 

37232 

37233 DESCRIPTION 

37234 The tsort utility shall write to standard output a totally ordered list of items consistent with a 

37235 partial ordering of items contained in the input. 

37236 The application shall ensure that the input consists of pairs of items (non-empty strings) I 

37237 separated by <blank>s. Pairs of different items indicate ordering. Pairs of identical items I 

37238 indicate presence, but not ordering. 

37239 OPTIONS 

37240 None. 

37241 OPERANDS 

37242 The following operand shall be supported: 

37243 file A path name of a text file to order. If no file operand is given, the standard input is 

37244 used. 


37245 STDIN 

37246 The standard input shall be a text file that is used if no file operand is given. 

37247 INPUT FILES 

37248 The input file named by the file operand is a text file. 


37249 ENVIRONMENT VARIABLES 

37250 The following environment variables shall affect the execution of tsort: 


37251 

37252 

37253 

37254 

37255 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37256 LC_ALL If set to a non-empty string value, override the values of all the other 

37257 internationalization variables. 


37258 

37259 

37260 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


37261 

37262 

37263 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


37264 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


37265 ASYNCHRONOUS EVENTS 

37266 Default. 


37267 STDOUT 

37268 The standard output shall be a text file consisting of the order list produced from the partially 

37269 ordered input. 
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37270 STDERR 

37271 Used only for diagnostic messages. 

37272 OUTPUT FILES 

37273 None. 

37274 EXTENDED DESCRIPTION 

37275 None. 

37276 EXIT STATUS 

37277 The following exit values shall be returned: 

37278 0 Successful completion. 

37279 >0 An error occurred. 

37280 CONSEQUENCES OF ERRORS 

37281 Default. 

37282 APPLICATION USAGE 

37283 The LC_COLLATE variable need not affect the actions of tsort. The output ordering is not 

37284 lexicographic, but depends on the pairs of items given as input. 

37285 EXAMPLES 

37286 The command: 

37287 tsort <<EOF 

37288 a b c c d e 

37289 g g 

37290 f g e f 

37291 h h 

37292 EOF 

37293 produces the output: 

37294 a 

37295 b 

37296 c 

37297 d 

37298 e 

37299 f 

37300 g 

37301 h 

37302 RATIONALE 

37303 None. 

37304 FUTURE DIRECTIONS 

37305 None. 

37306 SEE ALSO 

37307 None. 

37308 CHANGE HISTORY 

37309 First released in Issue 2. 

37310 Issue 4 

37311 Format reorganized. 

37312 Internationalized environment variable support mandated. 
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37313 Issue 6 

37314 The normative text is reworded to avoid use of the term "must” for application requirements. 
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37315 NAME 

37316 tty — return user's terminal name 

37317 SYNOPSIS 

37318 tty 

37319 DESCRIPTION 

37320 The tty utility shall write to the standard output the name of the terminal that is open as 

37321 standard input. The name that is used shall be equivalent to the string that would be returned by 

37322 the ttynamei ) function defined in the System Interfaces volume of IEEE Std. 1003.1-200x. 

37323 OPTIONS 

37324 The tty utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

37325 Section 12.2, Utility Syntax Guidelines. I 

37326 OPERANDS 

37327 None. 

37328 STDIN 

37329 While no input is read from standard input, standard input shall be examined to determine 

37330 whether or not it is a terminal, and, if so, to determine the name of the terminal. 

37331 INPUT FILES 

37332 None. 


37333 ENVIRONMENT VARIABLES 

37334 The following environment variables shall affect the execution of tty: 


37335 

37336 

37337 

37338 

37339 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37340 

37341 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


37342 

37343 

37344 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


37345 LC_MESSAGES 

37346 Determine the locale that should be used to affect the format and contents of 

37347 diagnostic messages written to standard error and informative messages written to 

37348 standard output. 

37349 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


37350 ASYNCHRONOUS EVENTS 

37351 Default. 


37352 STDOUT 

37353 If the -s option is not specified and standard input is a terminal device, a path name of the 

37354 terminal as specified by the ttyname{) function defined in the System Interfaces volume of 

37355 IEEE Std. 1003.1-200x shall be written in the following format: 

37356 "%s\n", <terminal name> 

37357 Otherwise, a message shall be written indicating that standard input is not connected to a 

37358 terminal. In the POSIX locale, the tty utility shall use the format: 
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37360 

37361 

37362 

37363 

37364 

37365 

37366 

37367 

37368 

37369 

37370 

37371 

37372 

37373 

37374 

37375 

37376 

37377 

37378 

37379 

37380 

37381 

37382 

37383 

37384 

37385 

37386 

37387 

37388 

37389 

37390 

37391 
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"not a tty\n" 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Standard input is a terminal. 

1 Standard input is not a terminal. 

>1 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

This utility checks the status of the file open as standard input against that of a system-defined 
set of files. It is possible that no match can be found, or that the match found need not be the 
same file as that which was opened for standard input (although they are the same device). 

The -s option is useful only if the exit code is wanted. It does not rely on the ability to form a 
valid path name. Portable applications should use test -t 0. 

EXAMPLES 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interfaces volume of IEEE Std. 1003.1-200x, isatty(), ttyname() 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 


Issue 5 

The SYNOPSIS is changed to indicate two forms of the command, with the second form marked 
as obsolete. This is a clarification and does not change the functionality published in previous 
issues. 
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37395 NAME 

37396 type — write a description of command type 

37397 SYNOPSIS 

37398 xsi type name. . . 

37399 

37400 DESCRIPTION 

37401 The type utility shall indicate how each argument would be interpreted if used as a command 

37402 name. 

37403 OPTIONS 

37404 None. 

37405 OPERANDS 

37406 The following operand shall be supported: 

37407 name A name to be interpreted. 

37408 STDIN 

37409 Not used. 

37410 INPUT FILES 

37411 None. 


37412 ENVIRONMENT VARIABLES 

37413 The following environment variables shall affect the execution of type: 


37414 

37415 

37416 

37417 

37418 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37419 LC_ALL If set to a non-empty string value, override the values of all the other 

37420 internationalization variables. 


37421 

37422 

37423 


LCJZTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


37424 

37425 

37426 


LCJAESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


37427 

37428 

37429 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

PATH Determine the location of name, as described in the System Interface Definitions I 

volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 


37430 ASYNCHRONOUS EVENTS 

37431 Default. 


37432 STDOUT 

37433 The standard output of type contains information about each operand in an unspecified format. 

37434 The information provided typically identifies the operand as a shell built-in, function, alias, or 

37435 keyword, and where applicable, may display the operand's path name. 
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37436 STDERR 

37437 Used only for diagnostic messages. 

37438 OUTPUT FILES 

37439 None. 

37440 EXTENDED DESCRIPTION 

37441 None. 

37442 EXIT STATUS 

37443 The following exit values shall be returned: 

37444 0 Successful completion. 

37445 >0 An error occurred. 

37446 CONSEQUENCES OF ERRORS 

37447 Default. 

37448 APPLICATION USAGE 

37449 Since type must be aware of the contents of the current shell execution environment (such as the 

37450 lists of commands, functions, and built-ins processed by hash), it is always provided as a shell 

37451 regular built-in. If it is called in a separate utility execution environment, such as one of the 

37452 following: 

37453 nohup type writer 

37454 find . —type f | xargs type 

37455 it might not produce accurate results. 

37456 EXAMPLES 

37457 None. 

37458 RATIONALE 

37459 None. 

37460 FUTURE DIRECTIONS 

37461 None. 

37462 SEE ALSO 

37463 command 

37464 CHANGE HISTORY 

37465 First released in Issue 2. 

37466 Issue 4 

37467 Relocated from the sh description to reflect its status as a regular built-in utility. 
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37468 NAME 

37469 ulimit — set or report file size limit 

37470 SYNOPSIS 

37471 xsi ulimit [—f ] [ blocks] 

37472 

37473 DESCRIPTION 

37474 The ulimit utility shall set or report the file-size writing limit imposed on files written by the 

37475 shell and its child processes (files of any size may be read). Only a process with appropriate 

37476 privileges can increase the limit. 

37477 OPTIONS 

37478 The ulimit utility shall conform to the System Interface Definitions volume of I 

37479 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37480 The following option shall be supported: 

37481 -f Set (or report, if no blocks operand is present), the file size limit in blocks. The -f 

37482 option shall also be the default case. 

37483 OPERANDS 

37484 The following operand shall be supported: 

37485 blocks The number of 512-byte blocks to use as the new file size limit. 

37486 STDIN 

37487 Not used. 

37488 INPUT FILES 

37489 None. 


37490 ENVIRONMENT VARIABLES 

37491 The following environment variables shall affect the execution of ulimit: 


37492 

37493 

37494 

37495 

37496 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37497 LC_ALL If set to a non-empty string value, override the values of all the other 

37498 internationalization variables. 


37499 

37500 

37501 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


37502 

37503 

37504 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


37505 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


37506 ASYNCHRONOUS EVENTS 

37507 Default. 
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37508 STDOUT 

37509 The standard output shall be used when no blocks operand is present. If the current number of 

37510 blocks is limited, the number of blocks in the current limit shall be written in the following 

37511 format: 

37512 "%d\n", <number of 512-byte blocks> 

37513 If there is no current limit on the number of blocks, in the POSIX locale the following format 

37514 shall be used: 

37515 "unlimited\n" 

37516 STDERR 

37517 Used only for diagnostic messages. 

37518 OUTPUT FILES 

37519 None. 

37520 EXTENDED DESCRIPTION 

37521 None. 

37522 EXIT STATUS 

37523 The following exit values shall be returned: 

37524 0 Successful completion. 

37525 >0 A request for a higher limit was rejected or an error occurred. 

37526 CONSEQUENCES OF ERRORS 

37527 Default. 

37528 APPLICATION USAGE 

37529 Since ulimit affects the current shell execution environment, it is always provided as a shell 

37530 regular built-in. If it is called in separate utility execution environment, such as one of the 

37531 following: 

37532 nohup ulimit — f 10000 

37533 env ulimit 10000 

37534 it does not affect the file size limit of the caller's environment. 

37535 Once a limit has been decreased by a process, it cannot be increased (unless appropriate 

37536 privileges are involved), even back to the original system limit. 

37537 EXAMPLES 

37538 Set the file size limit to 51200 bytes: 

37539 ulimit — f 100 

37540 RATIONALE 

37541 None. 

37542 FUTURE DIRECTIONS 

37543 None. 

37544 SEE ALSO 

37545 The System Interfaces volume of IEEE Std. 1003.1-200x, ulimit () 

37546 CHANGE HISTORY 

37547 First released in Issue 2. 


982 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


ulimit 


37548 Issue 4 

37549 Relocated from the sh description to reflect its status as a regular built-in utility. 


Commands and Utilities, Issue 6 


983 



umask 


Utilities 


37550 NAME 

37551 umask — get or set the file mode creation mask 

37552 SYNOPSIS 

37553 umask [— S] [mask] 


37554 DESCRIPTION 

37555 The umask utility shall set the file mode creation mask of the current shell execution 

37556 environment (see Section 2.12 on page 90) to the value specified by the mask operand. This mask 

37557 shall affect the initial value of the file permission bits of subsequently created files. If umask is 

37558 called in a subshell or separate utility execution environment, such as one of the following: 

37559 (uma s k 002) 

37560 nohup umask . . . 

37561 find . —exec umask ... \; 

37562 it shall not affect the file mode creation mask of the caller's environment. 

37563 If the mask operand is not specified, the umask utility shall write to standard output the value of 

37564 the invoking process's file mode creation mask. 

37565 OPTIONS 

37566 The umask utility shall conform to the System Interface Definitions volume of I 

37567 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37568 The following option shall be supported: 

37569 -S Produce symbolic output. 

37570 The default output style is unspecified, but shall be recognized on a subsequent invocation of 

37571 umask on the same system as a mask operand to restore the previous file mode creation mask. 

37572 OPERANDS 

37573 The following operand shall be supported: 

37574 mask A string specifying the new file mode creation mask. The string is treated in the 

37575 same way as the mode operand described in the the EXTENDED DESCRIPTION 

37576 section for chmod. 


37577 

37578 

37579 


For a symbolic_mode value, the new value of the file mode creation mask shall be 
the logical complement of the file permission bits portion of the file mode specified 
by the symbolic_mode string. 


37580 

37581 

37582 

37583 


In a symbolicjnode value, the permissions op characters '+' and shall be 
interpreted relative to the current file mode creation mask; ' +' shall cause the bits 
for the indicated permissions to be cleared in the mask; ' shall cause the bits for 
the indicated permissions to be set in the mask. 


37584 The interpretation of mode values that specify file mode bits other than the file 

37585 permission bits is unspecified. 


37586 man In the octal integer form of mode, the specified bits are set in the file mode creation 

37587 mask. 


37588 


The file mode creation mask shall be set to the resulting numeric value. 


37589 

37590 

37591 


The default output of a prior invocation of umask on the same system with no 
operand also shall be recognized as a mask operand. The use of an operand 
obtained in this way is not obsolescent, even if it is an octal number. 
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37592 STDIN 

37593 Not used. 

37594 INPUT FILES 

37595 None. 


37596 ENVIRONMENT VARIABLES 

37597 The following environment variables shall affect the execution of umask: 


37598 

37599 

37600 

37601 

37602 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37603 LC_ALL If set to a non-empty string value, override the values of all the other 

37604 internationalization variables. 


37605 

37606 

37607 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


37608 LC_MESSAGES 

37609 Determine the locale that should be used to affect the format and contents of 

37610 diagnostic messages written to standard error. 

37611 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


37612 ASYNCHRONOUS EVENTS 

37613 Default. 


37614 STDOUT 

37615 When the mask operand is not specified, the umask utility shall write a message to standard 

37616 output that can later be used as a umask mask operand. 

37617 If -S is specified, the message shall be in the following format: 

37618 "u=%s, g=%s, o=%s\n" , <owner permissions>, <group permissions>, 

37619 <other permissions> 

37620 where the three values shall be combinations of letters from the set j r, zv, x); the presence of a 

37621 letter shall indicate that the corresponding bit is clear in the file mode creation mask. 

37622 If a mask operand is specified, there shall be no output written to standard output. 

37623 STDERR 

37624 Used only for diagnostic messages. 

37625 OUTPUT FILES 

37626 None. 


37627 EXTENDED DESCRIPTION 

37628 None. 


37629 EXIT STATUS 

37630 The following exit values shall be returned: 

37631 0 The file mode creation mask was successfully changed, or no mask operand was supplied. 

37632 >0 An error occurred. 
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37633 

37634 

37635 

37636 

37637 

37638 

37639 

37640 

37641 

37642 

37643 

37644 

37645 

37646 

37647 

37648 

37649 

37650 

37651 

37652 

37653 

37654 

37655 

37656 

37657 

37658 

37659 

37660 

37661 

37662 

37663 

37664 

37665 

37666 

37667 

37668 

37669 

37670 

37671 

37672 

37673 

37674 


CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Since umask affects the current shell execution environment, it is generally provided as a shell 
regular built-in. 

In contrast to the negative permission logic provided by the file mode creation mask and the 
octal number form of the mask argument, the symbolic form of the mask argument specifies those 
permissions that are left alone. 

EXAMPLES 

Either of the commands: 

umask a=rx,ug+w 
umask 002 

sets the mode mask so that subsequently created files have their S_IWOTH bit cleared. 

After setting the mode mask with either of the above commands, the umask command can be 
used to write out the current value of the mode mask: 

$ umask 

0002 

(The output format is unspecified, but historical implementations use the obsolescent octal 
integer mode format.) 

$ umask —S 

u=rwx,g=rwx, o=rx 

Either of these outputs can be used as the mask operand to a subsequent invocation of the umask 
utility. 

Assuming the mode mask is set as above, the command: 

umask g—w 

sets the mode mask so that subsequently created files have their S_IWGRP and S_IWOTH bits 
cleared. 

The command: 

umask — —w 

sets the mode mask so that subsequently created files have all their write bits cleared. Note that 
mask operands -r, -w, -x or anything beginning with a hyphen, must be preceded by "—" to 
keep it from being interpreted as an option. 

RATIONALE 

Since umask affects the current shell execution environment, it is generally provided as a shell 
regular built-in. If it is called in a subshell or separate utility execution environment, such as one 
of the following: 

(umask 002) 
nohup umask . . . 
find . —exec umask ... \; 

it does not affect the file mode creation mask of the environment of the caller. 

The description of the historical utility was modified to allow it to use the symbolic modes of 
chmod. The -s option used in early proposals was changed to -S because -s could be confused 
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37675 with a symbolic_mode form of mask referring to the S_ISUID and S_ISGID bits. 

37676 Notes to Reviewers 

37677 This section zvith side shading will not appear in the final copy. - Ed. 

37678 Dl, XCU, ERN 355 suggests we should specify the default output. Suggestions please. 

37679 The default output style is implementation-dependent to permit implementors to provide 

37680 migration to the new symbolic style at the time most appropriate to their users. An -o flag to 

37681 force octal mode output was omitted because the octal mode may not be sufficient to specify all 

37682 of the information that may be present in the file mode creation mask when more secure file 

37683 access permission checks are implemented. 

37684 It has been suggested that trusted systems developers might appreciate ameliorating the 

37685 requirement that the mode mask "affects” the file access permissions, since it seems access 

37686 control lists might replace the mode mask to some degree. The wording has been changed to say 

37687 that it affects the file permission bits, and it leaves the details of the behavior of how they affect 

37688 the file access permissions to the description in the System Interfaces volume of 

37689 IEEE Std. 1003.1-200x. 

37690 FUTURE DIRECTIONS 

37691 None. 

37692 SEE ALSO 

37693 chmod, the System Interfaces volume of IEEE Std. 1003.1-200x, umask() 

37694 CHANGE HISTORY 

37695 First released in Issue 2. 

37696 Issue 4 

37697 Aligned with the ISO/IEC 9945-2:1993 standard. 

37698 Issue 6 

37699 The following new requirements on POSIX implementations derive from alignment with the 

37700 Single UNIX Specification: 

37701 • The octal mode is supported. 
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37702 NAME 

37703 unalias — remove alias definitions 

37704 SYNOPSIS 

37705 UP unalias alias-name. . . 

37706 unalias —a 

37707 

37708 DESCRIPTION 

37709 The unalias utility shall remove the definition for each alias name specified. See Section 2.3.1 on 

37710 P a g e 40. The aliases shall be removed from the current shell execution environment; see Section 

37711 2.12 on page 90. 

37712 OPTIONS 

37713 The unalias utility shall conform to the System Interface Definitions volume of I 

37714 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37715 The following option shall be supported: 

37716 -a Remove all alias definitions from the current shell execution environment. 

37717 OPERANDS 

37718 The following operand shall be supported: 

37719 alias-name The name of an alias to be removed. 

37720 STDIN 

37721 Not used. 

37722 INPUT FILES 

37723 None. 


37724 ENVIRONMENT VARIABLES 

37725 The following environment variables shall affect the execution of unalias: 


37726 

37727 

37728 

37729 

37730 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37731 

37732 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


37733 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

37734 characters (for example, single-byte as opposed to multi-byte characters in 

37735 arguments). 

37736 LC_MESSAGES 

37737 Determine the locale that should be used to affect the format and contents of 

37738 diagnostic messages written to standard error. 

37739 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

37740 ASYNCHRONOUS EVENTS 

37741 Default. 
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37742 STDOUT 

37743 Not used. 

37744 STDERR 

37745 Used only for diagnostic messages. 

37746 OUTPUT FILES 

37747 None. 

37748 EXTENDED DESCRIPTION 

37749 None. 

37750 EXIT STATUS 

37751 The following exit values shall be returned: 

37752 0 Successful completion. 

37753 >0 One of the alias-name operands specified did not represent a valid alias definition, or an 

37754 error occurred. 

37755 CONSEQUENCES OF ERRORS 

37756 Default. 

37757 APPLICATION USAGE 

37758 Since unalias affects the current shell execution environment, it is generally provided as a shell 

37759 regular built-in. 

37760 Application writers should note that this utility need not be provided on systems that do not 

37761 support the User Portability Utilities option. 

37762 EXAMPLES 

37763 None. 

37764 RATIONALE 

37765 The unalias description is based on that from historical KomShell implementations. Known 

37766 differences exist between that and the C shell. The KomShell version was adopted to be 

37767 consistent with all the other KomShell features in this volume of IEEE Std. 1003.1-200x, such as I 

37768 command line editing. I 

37769 The -a option is the equivalent of the unalias* form of the C shell and is provided to address 

37770 security concerns about unknown aliases entering the environment of a user (or application) 

37771 through the allowable implementation-dependent predefined alias route or as a result of an ENV 

37772 file. (Although unalias could be used to simplify the "secure” shell script shown in the command 

37773 rationale, it does not obviate the need to quote all command names. An initial call to unalias -a 

37774 would have to be quoted in case there was an alias for unalias.) 

37775 FUTURE DIRECTIONS 

37776 None. 

37777 SEE ALSO 

37778 alias 

37779 CHANGE HISTORY 

37780 First released in Issue 4. 

37781 Issue 6 

37782 This utility is now marked as part of the User Portability Utilities option. 
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37783 NAME 

37784 uname — return system name 

37785 SYNOPSIS 

37786 uname [—snrvma] 

37787 DESCRIPTION 

37788 By default, the uname utility shall write the operating system name to standard output. When 

37789 options are specified, symbols representing one or more system characteristics shall be written 

37790 to the standard output. The format and contents of the symbols are implementation-dependent. 

37791 On systems conforming to the System Interfaces volume of IEEE Std. 1003.1-200x, the symbols 

37792 written shall be those supported by the uname( ) function as defined in the System Interfaces 

37793 volume of IEEE Std. 1003.1-200x. 

37794 OPTIONS 

37795 The uname utility shall conform to the System Interface Definitions volume of I 

37796 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37797 The following options shall be supported: 


37798 

-a 

Behave as though all of the options -mnrsv were specified. 

37799 

-m 

Write the name of the hardware type on which the system is running to standard 

37800 


output. 

37801 

-n 

Write the name of this node within an implementation-dependent 

37802 


communications network. 

37803 

-r 

Write the current release level of the operating system implementation. 

37804 

-s 

Write the name of the implementation of the operating system. 

37805 

-v 

Write the current version level of this release of the operating system 

37806 


implementation. 

37807 

If no options 

are specified, the uname utility shall write the operating system name, as if the -s 

37808 

option had been specified. 

37809 OPERANDS 


37810 

None. 


37811 STDIN 



37812 

Not used. 


37813 INPUT FILES 


37814 

None. 


37815 ENVIRONMENT VARIABLES 

37816 

The following environment variables shall affect the execution of uname: 

37817 

LANG 

Provide a default value for the internationalization variables that are unset or null. 

37818 


If LANG is unset or null, the corresponding value from the implementation- 

37819 


dependent default locale shall be used. If any of the internationalization variables 

37820 


contains an invalid setting, the utility shall behave as if none of the variables had 

37821 


been defined. 

37822 

LC_ALL 

If set to a non-empty string value, override the values of all the other 

37823 


internationalization variables. 

37824 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 

37825 


characters (for example, single-byte as opposed to multi-byte characters in 
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37826 arguments). 

37827 LC_MESSAGES 

37828 Determine the locale that should be used to affect the format and contents of 

37829 diagnostic messages written to standard error. 

37830 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

37831 ASYNCHRONOUS EVENTS 

37832 Default. 

37833 STDOUT 

37834 By default, the output shall be a single line of the following form: 

37835 "%s\n", <sysname> 

37836 If the -a option is specified, the output shall be a single line of the following form: 

37837 "%s %s %s %s %s\n", <sysname>, <nodename>, <release>, 

37838 <version>, <machine> 

37839 Additional implementation-dependent symbols may be written; all such symbols shall be 

37840 written at the end of the line of output before the <newline> character. 

37841 If options are specified to select different combinations of the symbols, only those symbols shall 

37842 be written, in the order shown above for the -a option. If a symbol is not selected for writing, its 

37843 corresponding trailing <blank> characters also shall not be written. 

37844 STDERR 

37845 Used only for diagnostic messages. 

37846 OUTPUT FILES 

37847 None. 

37848 EXTENDED DESCRIPTION 

37849 None. 

37850 EXIT STATUS 

37851 The following exit values shall be returned: 

37852 0 The requested information was successfully written. 

37853 >0 An error occurred. 

37854 CONSEQUENCES OF ERRORS 

37855 Default. 

37856 APPLICATION USAGE 

37857 Note that any of the symbols could include embedded <space> characters, which may affect 

37858 parsing algorithms if multiple options are selected for output. 

37859 The node name is typically a name that the system uses to identify itself for intersystem 

37860 communication addressing. 

37861 EXAMPLES 

37862 The following command: 

37863 uname —sr 

37864 writes the operating system name and release level, separated by one or more <blank> 

37865 characters. 
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37866 RATIONALE 

37867 It was suggested that this utility cannot be used portably since the format of the symbols is 

37868 implementation-dependent. The POSIX.l working group could not achieve consensus on 

37869 defining these formats in the underlying uname ( ) function, and there was no expectation that 

37870 this volume of IEEE Std. 1003.1-200x would be any more successful. Some applications may still 

37871 find this historical utility of value. For example, the symbols could be used for system log entries 

37872 or for comparison with operator or user input. 

37873 FUTURE DIRECTIONS 

37874 None. 

37875 SEE ALSO 

37876 The System Interfaces volume of IEEE Std. 1003.1-200x, uname {) 

37877 CHANGE HISTORY 

37878 First released in Issue 2. 

37879 Issue 4 

37880 Aligned with the ISO/IEC 9945-2:1993 standard. 

37881 Issue 4, Version 2 

37882 The SYNOPSIS section lists all the valid options. 
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37883 NAME 

37884 uncompress — expand compressed data 

37885 SYNOPSIS 

37886 xsi uncompress [— cfv] [file. . .] 

37887 


37888 DESCRIPTION 

37889 The uncompress utility shall restore files to their original state after they have been compressed 

37890 using the compress utility. If no files are specified, the standard input shall be uncompressed to 

37891 the standard output. If the invoking process has appropriate privileges, the ownership, modes, 

37892 access time, and modification time of the original file shall be preserved. 

37893 This utility shall support the uncompressing of any files produced by the compress utility on the 

37894 same implementation. For files produced by compress on other systems, uncompress supports 9 to 

37895 14-bit compression (see compress on page 299, -b); it is implementation-dependent whether 

37896 values of -b greater than 14 are supported. 


37897 OPTIONS 

37898 The uncompress utility shall conform to the System Interface Definitions volume of I 

37899 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37900 The following options shall be supported: 


37901 -C 


Write to standard output; no files are changed. 


37902 -f 

37903 

37904 

37905 

37906 


Do not prompt for overwriting files. Except when run in the background, if -f is 
not given the user shall be prompted as to whether an existing file should be 
overwritten. If the standard input is not a terminal and -f is not given, uncompress 
shall write a diagnostic message to standard error and exit with a status greater 
than zero. 


37907 -v Write messages to standard error concerning the expansion of each file. 

37908 OPERANDS 

37909 The following operand shall be supported: 


37910 file 

37911 

37912 

37913 


A path name of a file. If file already has the .Z suffix specified, it shall be used as 
the input file and the output file shall be named file with the .Z suffix removed. 
Otherwise, file shall be used as the name of the output file and file with the .Z 
suffix appended shall be used as the input file. 


37914 STDIN 

37915 The standard input shall be used only if no file operands are specified, or if a file operand is ' . 


37916 INPUT FILES 

37917 Input files shall be in the format produced by the compress utility. 


37918 ENVIRONMENT VARIABLES 

37919 The following environment variables shall affect the execution of uncompress : 


37920 

37921 

37922 

37923 

37924 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


37925 

37926 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 
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37927 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

37928 characters (for example, single-byte as opposed to multi-byte characters in 

37929 arguments). 

37930 LC_MESSAGES 

37931 Determine the locale that should be used to affect the format and contents of 

37932 diagnostic messages written to standard error. 

37933 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

37934 ASYNCHRONOUS EVENTS 

37935 Default. 

37936 STDOUT 

37937 When there are no file operands or the -c option is specified, the uncompressed output is 

37938 written to standard output. 

37939 STDERR 

37940 Prompts shall be written to the standard error output under the conditions specified in the 

37941 DESCRIPTION and OPTIONS sections. The prompts shall contain the file path name, but their 

37942 format is otherwise unspecified. Otherwise, the standard error output shall be used only for 

37943 diagnostic messages. 

37944 OUTPUT FILES 

37945 Output files are the same as the respective input files to compress. 

37946 EXTENDED DESCRIPTION 

37947 None. 

37948 EXIT STATUS 

37949 The following exit values shall be returned: 

37950 0 Successful completion. 

37951 >0 An error occurred. 

37952 CONSEQUENCES OF ERRORS 

37953 The input file remains unmodified. 

37954 APPLICATION USAGE 

37955 The limit of 14 on the compress -b bits argument is to achieve portability to all systems (within 

37956 the restrictions imposed by the lack of an explicit published file format). Some systems based on 

37957 16-bit architectures cannot support 15 or 16-bit uncompression. 

37958 EXAMPLES 

37959 None. 

37960 RATIONALE 

37961 None. 

37962 FUTURE DIRECTIONS 

37963 None. 

37964 SEE ALSO 

37965 compress , zcat 

37966 CHANGE HISTORY 

37967 First released in Issue 4. 
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37968 Issue 4, Version 2 

37969 The DESCRIPTION is clarified to state that the ownership, modes, access time, and modification 

37970 time of the original file are preserved if the invoking process has appropriate privileges. 

37971 Issue 6 

37972 The normative text is reworded to avoid use of the term "must” for application requirements. 
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37973 NAME 

37974 unexpand — convert spaces to tabs 

37975 SYNOPSIS 

37976 UP unexpand [ —a | —t tablist] [file. . . ] 

37977 

37978 DESCRIPTION 

37979 The itnexpand utility shall copy files or standard input to standard output, converting <blank> 

37980 characters at the beginning of each line into the maximum number of <tab> characters followed 

37981 by the minimum number of <space> characters needed to fill the same column positions 

37982 originally filled by the translated <blank> characters. By default, tabstops shall be set at every 

37983 eighth column position. Each <backspace> character shall be copied to the output, and shall 

37984 cause the column position count for tab calculations to be decremented; the count shall never be 

37985 decremented to a value less than one. 


37986 OPTIONS 

37987 The unexpand utility shall conform to the System Interface Definitions volume of I 

37988 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

37989 The following options shall be supported: 


37990 -a 

37991 

37992 

37993 

37994 


In addition to translating <blank> characters at the beginning of each line, translate 
all sequences of two or more <blank> characters immediately preceding a tab stop 
to the maximum number of <tab> characters followed by the minimum number of 
<space> characters needed to fill the same column positions originally filled by the 
translated <blank> characters. 


37995 

37996 

37997 

37998 

37999 

38000 


-t tablist Specify the tab stops. The application shall ensure that the tablist option-argument I 
is a single argument consisting of a single positive decimal integer or multiple I 
positive decimal integers, separated by <blank> characters or commas, in I 
ascending order. If a single number is given, tabs shall be set tablist column 
positions apart instead of the default 8. If multiple numbers are given, the tabs 
shall be set at those specific column positions. 


38001 

38002 

38003 

38004 

38005 

38006 


The application shall ensure that each tab-stop position N is an integer value I 
greater than zero, and the list shall be in strictly ascending order. This is taken to I 
mean that, from the start of a line of output, tabbing to position N shall cause the I 
next character output to be in the (N+l)th column position on that line. When the 
-t option is not specified, the default shall be the equivalent of specifying -t 8 
(except for the interaction with -a, described below). 


38007 No <space>-to-<tab> character conversions shall occur for characters at positions 

38008 beyond the last of those specified in a multiple tab-stop list. 


38009 When -t is specified, the presence or absence of the -a option shall be ignored; 

38010 conversion shall not be limited to the processing of leading <blank> characters. 


38011 OPERANDS 

38012 The following operand shall be supported: 


38013 file A path name of a text file to be used as input. 


38014 STDIN 

38015 See the INPUT FILES section. 
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38016 INPUT FILES 

38017 The input files shall be text files. 


38018 ENVIRONMENT VARIABLES 

38019 The following environment variables shall affect the execution of unexpand : 


38020 

38021 

38022 

38023 

38024 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


38025 

38026 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


38027 

38028 

38029 

38030 

38031 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files), the processing of <tab> and <space> characters and for 
the determination of the width in column positions each character would occupy I 
on an output device. I 


38032 LC_MESSAGES 

38033 Determine the locale that should be used to affect the format and contents of 

38034 diagnostic messages written to standard error. 

38035 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


38036 ASYNCHRONOUS EVENTS 

38037 Default. 


38038 STDOUT 

38039 The standard output is equivalent to the input files with the specified <space>-to-<tab> 

38040 character conversions. 


38041 STDERR 

38042 Used only for diagnostic messages. 

38043 OUTPUT FILES 

38044 None. 


38045 EXTENDED DESCRIPTION 

38046 None. 


38047 EXIT STATUS 

38048 The following exit values shall be returned: 

38049 0 Successful completion. 

38050 >0 An error occurred. 


38051 CONSEQUENCES OF ERRORS 

38052 Default. 
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38053 

38054 

38055 

38056 

38057 

38058 

38059 

38060 

38061 

38062 

38063 

38064 

38065 

38066 

38067 

38068 

38069 

38070 

38071 

38072 

38073 

38074 

38075 

38076 

38077 

38078 

38079 

38080 

38081 


APPLICATION USAGE 

One non-intuitive aspect of unexpand is its restriction to leading spaces when neither -a nor -t is 
specified. Users who desire to always convert all spaces in a file can easily alias unexpand to use 
the -a or -t 8 option. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

On several occasions, consideration was given to adding a -t option to the unexpand utility to 
complement the -t in expand (see expand on page 460). The historical intent of unexpand was to 
translate multiple <blank>s into tab stops, where tab stops were a multiple of eight column 
positions on most UNIX systems. An early proposal omitted -t because it seemed outside the 
scope of the UPE; it was not described in any of the base documents. However, hard-coding tab 
stops every eight columns was not suitable for the international community and broke historical 
precedents for some vendors in the FORTRAN community, so -t was restored in conjunction 
with the list of valid extension categories considered by the standard developers. Thus, unexpand 
is now the logical converse of expand. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

expand, tabs 

CHANGE HISTORY 

First released in Issue 4. 


Issue 6 

This utility is now marked as part of the User Portability Utilities option. I 

The definition of the LC_CTYPE environment variable is changed to align with the I 
IEEE P1003.2b draft standard. I 

The normative text is reworded to avoid use of the term "must” for application requirements. I 
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38082 NAME 

38083 unget — undo a previous get of an SCCS file (DEVELOPMENT) 

38084 SYNOPSIS 

38085 xsi unget [—ns] [— r SID ] file. . . 

38086 


38087 DESCRIPTION 

38088 The unget utility shall reverse the effect of a get -e done prior to creating the intended new delta. 


38089 OPTIONS 

38090 The unget utility shall conform to the System Interface Definitions volume of I 

38091 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

38092 The following options shall be supported: 


38093 

38094 

38095 

38096 


-r SID Uniquely identify which delta is no longer intended. (This would have been 

specified by get as the new delta.) The use of this option is necessary only if two or 
more outstanding get commands for editing on the same SCCS file were done by 
the same person (login name). 


38097 -S 


Suppress the writing to standard output of the intended delta's SID. 


38098 -n Retain the file that was obtained by get, which would normally be removed from 

38099 the current directory. 


38100 OPERANDS 

38101 The following operands shall be supported: 


38102 file 

38103 

38104 

38105 


A path name of an existing SCCS file or a directory. If file is a directory, unget 
behaves as though each file in the directory were specified as a named file, except 
that non-SCCS files (last component of the path name does not begin with s.) and 
unreadable files shall be silently ignored. 


38106 

38107 

38108 


If a single instance file is specified as ' —', the standard input shall be read; each 
line of the standard input is taken to be the name of an SCCS file to be processed. 
Non-SCCS files and unreadable files shall be silently ignored. 


38109 STDIN 

38110 The standard input shall be a text file used only when the file operand is specified as ' . Each I 

38111 line of the text file shall be interpreted as an SCCS path name. 


38112 INPUT FILES 

38113 Any SCCS files processed are files of an unspecified format. 


38114 ENVIRONMENT VARIABLES 


38115 

The following environment variables shall affect the execution of unget: 

38116 

38117 

38118 

38119 

38120 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

38121 

38122 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

38123 

38124 

38125 

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 
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38126 

38127 

38128 

38129 

38130 

38131 

38132 

38133 

38134 

38135 

38136 

38137 

38138 

38139 

38140 

38141 

38142 

38143 

38144 

38145 

38146 

38147 

38148 

38149 

38150 

38151 

38152 

38153 

38154 

38155 

38156 

38157 

38158 

38159 

38160 

38161 

38162 

38163 

38164 

38165 

38166 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall consist of a line for each file, in the following format: 

"%s\n", <SID removed from file> 

If there is more than one named file or if a directory or standard input is named, each path name 
shall be written before each of the preceding lines: 

"\n%s:\n", <pathname> 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

Any SCCS files updated are files of an unspecified format. During processing of a file, a locking 
z-file, as described in get, and a q-file (a working copy of the p-file), may be created and deleted. 
The p-file and g-file, as described in get, shall be deleted. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

None. 

EXAMPLES 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

delta, get, sact 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Format reorganized. 

Utility Syntax Guidelines support mandated. 
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38167 

38168 

38169 


Internationalized environment variable support mandated. 

Issue 6 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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38170 NAME 

38171 uniq — report or filter out repeated lines in a file 

38172 SYNOPSIS 

38173 uniq [—c | —d | —u] [—f fields] [-s char] [input_file [output_file] ] 

38174 DESCRIPTION 

38175 The uniq utility shall read an input file comparing adjacent lines, and writes one copy of each 

38176 input line on the output. The second and succeeding copies of repeated adjacent input lines shall 

38177 not be written. 


38178 Repeated lines in the input shall not be detected if they are not adjacent. 


38179 OPTIONS 

38180 The uniq utility shall conform to the System Interface Definitions volume of I 

38181 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

38182 The following options shall be supported: 


38183 -c Precede each output line with a count of the number of times the line occurred in 

38184 the input. 


38185 -d 


Suppress the writing of lines that are not repeated in the input. 


38186 

38187 

38188 


-f fields Ignore the first fields fields on each input line when doing comparisons, where 

fields is a positive decimal integer. A field is the maximal string matched by the 
basic regular expression: 


38189 


[ [ :blank:]]*['[:blank:]]* 


38190 If the fields option-argument specifies more fields than appear on an input line, a 

38191 null string shall be used for comparison. 


38192 

38193 

38194 

38195 

38196 


-s clmrs Ignore the first chars characters when doing comparisons, where chars shall be a 
positive decimal integer. If specified in conjunction with the -f option, the first 
chars characters after the first fields fields shall be ignored. If the chars option- 
argument specifies more characters than remain on an input line, a null string shall 
be used for comparison. 


38197 -U 


Suppress the writing of lines that are repeated in the input. 


38198 OPERANDS 

38199 The following operands shall be supported: 


38200 input Jile A path name of the input file. If the input Jile operand is not specified, or if the 

38201 input Jile is ' , the standard input is used. 


38202 

38203 

38204 


output Jile A path name of the output file. If the output Jile operand is not specified, the 

standard output shall be used. The results are unspecified if the file named by 
output Jile is the file named by input Jile. 


38205 STDIN 

38206 The standard input shall be used only if no input Jile operand is specified or if input Jile is ' . 

38207 See the INPUT FILES section. 


38208 INPUT FILES 

38209 The input file shall be a text file. 
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38210 ENVIRONMENT VARIABLES 

38211 The following environment variables shall affect the execution of uniq: 


38212 

38213 

38214 

38215 

38216 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


38217 LC_ALL If set to a non-empty string value, override the values of all the other 

38218 internationalization variables. 


38219 

38220 

38221 

38222 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) which characters constitute a <blank> character in the 
current locale. 


38223 LC_MESSAGES 

38224 Determine the locale that should be used to affect the format and contents of 

38225 diagnostic messages written to standard error. 

38226 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

38227 ASYNCHRONOUS EVENTS 

38228 Default. 


38229 STDOUT 

38230 The standard output shall be used only if no output_fite operand is specified. See the OUTPUT 

38231 FILES section. 


38232 STDERR 

38233 Used only for diagnostic messages. 

38234 OUTPUT FILES 

38235 If the -c option is specified, the application shall ensure that the output file is empty or each line I 

38236 shall be of the form: I 

38237 "%d %s", <number of duplicates>, <line> 

38238 otherwise, the application shall ensure that the output file is empty or each line shall be of the I 

38239 form: I 

38240 "%s", <line> 

38241 EXTENDED DESCRIPTION 

38242 None. 


38243 EXIT STATUS 

38244 The following exit values shall be returned: 

38245 0 The utility executed successfully. 

38246 >0 An error occurred. 


38247 CONSEQUENCES OF ERRORS 

38248 Default. 
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38249 

38250 

38251 

38252 

38253 

38254 

38255 

38256 

38257 

38258 

38259 

38260 

38261 

38262 

38263 

38264 

38265 

38266 

38267 

38268 

38269 

38270 

38271 

38272 

38273 

38274 

38275 

38276 

38277 

38278 

38279 

38280 

38281 

38282 

38283 

38284 

38285 

38286 

38287 

38288 

38289 

38290 

38291 

38292 


APPLICATION USAGE 

The sort utility can be used to cause repeated lines to be adjacent in the input file. 

EXAMPLES 

The following input file data (but flushed left) was used for a test series on uniq: 

#01 fooO barO fool barl 

#02 barO fool barl fool 

#03 fooO barO fool barl 

#04 

#05 fooO barO fool barl 

#06 fooO barO fool barl 

#07 barO fool barl fooO 

What follows is a series of test invocations of the uniq utility that use a mixture of uniq options 
against the input file data. These tests verify the meaning of adjacent. The uniq utility views the 
input data as a sequence of strings delimited by ' \n'. Accordingly, for the fields th member of 
the sequence, uniq interprets unique or repreated adjacent lines strictly relative to the fields +t th 
member. 

1. This first example tests the line counting option, comparing each line of the input file data 
starting from the second field: 

uniq —c —f 1 uniq_0I.t 

1 #01 fooO barO fool barl 
1 #02 barO fool barl fooO 
1 #03 fooO barO fool barl 

1 #04 

2 #05 fooO barO fool barl 
1 #07 barO fool barl fooO 

The number ' 2', prefixing the fifth line of output, signifies that the uniq utility detected a 
pair of repeated lines. Given the input data, this can only be true when uniq is run using 
the -f 1 option (which shall cause uniq to ignore the first field on each input line). 

2. The second example tests the option to suppress unique lines, comparing each line of the 
input file data starting from the second field: 

uniq —d —f 1 uniq_0I.t 
#05 fooO barO fool barl 

3. This test suppresses repeated lines, comparing each line of the input file data starting from 
the second field: 

uniq —u —f 1 uniq_0I.t 
#01 fooO barO fool barl 

#02 barO fool barl fool 

#03 fooO barO fool barl 

#04 

#07 barO fool barl fooO 

4. This suppresses unique lines, comparing each line of the input file data starting from the 
third character: 

uniq —d —s 2 uniq_0I.t 

In the last example, the uniq utility found no input matching the above criteria. 


1004 


Technical Standard (2000) (Draft February 29, 2000) 



Utilities 


umq 


38293 RATIONALE 

38294 Some historical implementations have limited lines to be 1080 bytes in length, which does not 

38295 meet the implied {LINE_MAX[ limit. 

38296 The -f and -s options were added to replace the obsolescent -n and +m options so that iiniq 

38297 could meet the syntax guidelines in an upward-compatible way. 

38298 FUTURE DIRECTIONS 

38299 None. 

38300 SEE ALSO 

38301 comm, sort 

38302 CHANGE HISTORY 

38303 First released in Issue 2. 

38304 Issue 4 

38305 Aligned with the ISO/IEC 9945-2:1993 standard. 

38306 Issue 6 

38307 The obsolescent SYNOPSIS and associated text are removed. 

38308 The normative text is reworded to avoid use of the term "must” for application requirements. 
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38309 NAME 

38310 unlink — call the unlink( ) function 

38311 SYNOPSIS 

38312 xsi unlink file 

38313 

38314 DESCRIPTION 

38315 The unlink utility shall perform the function call: 

38316 unlink ( file) ; 

38317 A user may need appropriate privilege to invoke the unlink utility. 

38318 OPTIONS 

38319 None. 

38320 OPERANDS 

38321 The following operands shall be supported: 

38322 file The path name of an existing file. 

38323 STDIN 

38324 Not used. 

38325 INPUT FILES 

38326 Not used. 


38327 ENVIRONMENT VARIABLES 

38328 The following environment variables shall affect the execution of unlink: 


38329 

38330 

38331 

38332 

38333 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contain an invalid setting, the utility behaves as if none of the variables had been 
set. 


38334 LC_ALL If set to a non-empty string value, override the values of all the other 

38335 internationalization variables. 


38336 

38337 

38338 


LCjCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


38339 

38340 

38341 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


38342 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


38343 ASYNCHRONOUS EVENTS 

38344 Default. 


38345 STDOUT 

38346 None. 


38347 STDERR 

38348 Used only for diagnostic messages. 
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38349 OUTPUT FILES 

38350 None. 

38351 EXTENDED DESCRIPTION 

38352 None. 

38353 EXIT STATUS 

38354 The following exit values shall be returned: 

38355 0 Successful completion. 

38356 >0 An error occurred. 

38357 CONSEQUENCES OF ERRORS 

38358 Default. 

38359 APPLICATION USAGE 

38360 None. 

38361 EXAMPLES 

38362 None. 

38363 RATIONALE 

38364 None. 

38365 FUTURE DIRECTIONS 

38366 None. 

38367 SEE ALSO 

38368 link, rm, the System Interfaces volume of IEEE Std. 1003.1-200x, unlink() 

38369 CHANGE HISTORY 

38370 First released in Issue 5. 
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38371 NAME 

38372 uucp — system-to-system copy 

38373 SYNOPSIS 

38374 UN xsi uucp [—cCdf jmr] [—n user] source-file . . . destination-file 

38375 

38376 DESCRIPTION 

38377 The uucp utility shall copy files named by the source-file arguments to the destination-file 

38378 argument. The files named can be on local or remote systems. 

38379 The uucp utility cannot guarantee support for all character encodings in all circumstances. For 

38380 example, transmission data may be restricted to 7 bits by the underlying network, 8-bit data and 

38381 file names need not be portable to non-intemationalized systems, and so on. Under these 

38382 circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 

38383 standard International Reference Version (equivalent to ASCII) 7-bit range of characters be used, 

38384 and that only characters defined in the Portable File Name Character Set be used for naming 

38385 files. 


38386 OPTIONS 


38387 

38388 

The uucp utility shall conform to the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. 

38389 

The following options shall be supported: 

38390 

38391 

-c 

Do not copy local file to the spool directory for transfer to the remote machine 
(default). 

38392 UN 

-C 

Force the copy of local files to the spool directory for transfer. 

38393 

-d 

Make all necessary directories for the file copy (default). 

38394 UN 

-f 

Do not make intermediate directories for the file copy. 

38395 UN 

38396 

-j 

Write the job identification string to standard output. This job identification can be 
used by uustat to obtain the status or terminate a job. 

38397 

-m 

Send mail to the requester when the copy is completed. 

38398 UN 

-n user 

Notify user on the remote system that a file was sent. 


38399 un -r Do not start the file transfer; just queue the job. 

38400 OPERANDS 

38401 The following operands shall be supported: 


38402 

38403 

38404 

38405 

38406 

38407 


destination-file, source-file 

A path name of a file to be copied to, or from, respectively. Either name can be a 
path name on the local machine, or can have the form: 

system-name!pathname 

where system-name is taken from a list of system names that uucp knows about. 
The destination system-name can also be a list of names such as: 


38408 


system-name ! system-name !... I system-namelpathname 


38409 

38410 

38411 


in which case, an attempt is made to send the file via the specified route to the 
destination. Care should be taken to ensure that intermediate nodes in the route 
are willing to forward information. 
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38412 The shell pattern matching notation characters and appearing 

38413 in pathname are expanded on the appropriate system. 


38414 


Path names can be one of: 


38415 

38416 

38417 

38418 

38419 


1. An absolute path name. 

2. A path name preceded by ~nser where user is a login name on the specified 
system and is replaced by that user's login directory. Note that if an invalid 
login is specified, the default is to the public directory (called PUBDIR ; the 
actual location of PUBDIR is implementation-dependent). 


38420 

38421 


3. A path name preceded by ~/destination where destination is appended to 
PUBDIR. 


38422 

38423 

38424 

38425 

38426 

38427 

38428 

38429 

38430 

38431 

38432 

38433 STDIN 

38434 Not used. 


Note: This destination is treated as a file name unless more than one file 

is being transferred by this request or the destination is already a 
directory. To ensure that it is a directory, follow the destination 
with a ' / '. For example, 7dan/ as the destination makes the 
directory PUBDIR/dan if it does not exist and put the requested 
files in that directory. 

4. Anything else is prefixed by the current directory. 

If the result is an erroneous path name for the remote system, the copy fails. If the 
destination-file is a directory, the last part of the source-file name is used. 

The read, write, and execute permissions given by uucp are implementation- 
dependent. 


38435 INPUT FILES 

38436 The files to be copied are regular files. 


38437 ENVIRONMENT VARIABLES 

38438 The following environment variables shall affect the execution of uucp-. 


38439 

38440 

38441 

38442 

38443 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


38444 LC_ALL If set to a non-empty string value, override the values of all the other 

38445 internationalization variables. 


38446 

38447 

38448 


LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements within bracketed file name patterns. 


38449 

38450 

38451 

38452 


LCJZTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes within bracketed 
file name patterns (for example, " ' [ [: lower :]]*'"). 


38453 LCJAESSAGES 

38454 Determine the locale that should be used to affect the format and contents of 

38455 diagnostic messages written to standard error, and informative messages written 
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38456 to standard output. 

38457 LC_TIME Determine the format of date and time strings output by uucp. 

38458 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

38459 TZ Determine the timezone used with date and time strings. 

38460 ASYNCHRONOUS EVENTS 

38461 Default. 

38462 STDOUT 

38463 Not used. 

38464 STDERR 

38465 Used only for diagnostic messages. 

38466 OUTPUT FILES 

38467 The output files (which may be on other systems) are copies of the input files. 

38468 If the -m is used, mail files are modified. 

38469 EXTENDED DESCRIPTION 

38470 None. 

38471 EXIT STATUS 

38472 The following exit values shall be returned: 

38473 0 Successful completion. 

38474 >0 An error occurred. 

38475 CONSEQUENCES OF ERRORS 

38476 Default. 

38477 APPLICATION USAGE 

38478 The domain of remotely accessible files can (and for obvious security reasons usually should) be 

38479 severely restricted. 

38480 Note that the ' !' character in addresses has to be escaped when using csh as a command 

38481 interpreter because of its history substitution syntax. For ksh and sh the escape is not necessary, 

38482 but may be used. 

38483 Typical implementations of this utility require a communications line configured to use the I 

38484 System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 

38485 Interface, but other communications means may be used. On systems where there are no I 

38486 available communications means (either temporarily or permanently), this utility shall write an 

38487 error message describing the problem and exit with a non-zero exit status. 

38488 As noted above, shell metacharacters appearing in path names are expanded on the appropriate 

38489 system. On an internationalized system, this is done under the control of local settings of 

38490 LCjCOLLATE and LCJCTYPE. Thus, care should be taken when using bracketed file name 

38491 patterns, as collation and typing rules may vary from one system to another. Also be aware that 

38492 certain types of expression (that is, equivalence classes, character classes, and collating symbols) 

38493 need not be supported on non-intemationalized systems. 

38494 EXAMPLES 

38495 None. 
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38496 RATIONALE 

38497 None. 

38498 FUTURE DIRECTIONS 

38499 None. 

38500 SEE ALSO 

38501 mailx, intencode, uustat, uux 

38502 CHANGE HISTORY 

38503 First released in Issue 2. 

38504 Issue 4 

38505 Format reorganized. 

38506 Split into a separate description. 

38507 Utility Syntax Guidelines support mandated. 

38508 Internationalized environment variable support mandated. 

38509 Presence of the utility mandated, even on systems where no communications are available. 
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38510 NAME 

38511 uudecode — decode a binary file 

38512 SYNOPSIS 

38513 up uudecode [—o out file] [file] I 

38514 | 

38515 DESCRIPTION 

38516 The uudecode utility shall read a file, or standard input if no file is specified, that includes data I 

38517 created by the intencode utility. The uudecode utility shall scan the input file, searching for data 

38518 compatible with one of the formats specified in intencode and attempt to create or overwrite the I 

38519 file described by the data (or overridden by the -o option). The path name shall be contained in I 

38520 the data or specified by the -o option. The file access permission bits and contents for the file to I 

38521 be produced shall be contained in that data. The mode bits of the created file (other than I 

38522 standard output) shall be set from the file access permission bits contained in the data; that is, I 

38523 other attributes of the mode, including the file mode creation mask (see umask), shall not affect I 

38524 the file being produced. 

38525 If the path name of the file to be produced exists, and the user does not have write permission on 

38526 that file, uudecode shall terminate with an error. If the path name of the file to be produced exists, 

38527 and the user has write permission on that file, the existing file shall be overwritten. 

38528 If the input data was produced by uuencode on a system with a different number of bits per byte 

38529 than on the target system, the results of uudecode are unspecified. 

38530 OPTIONS 

38531 The uudecode utility shall conform to the System Interface Definitions volume of I 

38532 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

38533 The following option shall be supported by the implementation: I 

38534 -o outfile A path name of a file that shall be used instead of any path name contained in the I 

38535 input data. Specifying an outfile option-argument of /dev/stdout shall indicate I 

38536 standard output. I 

38537 OPERANDS I 

38538 The following operand shall be supported: 

38539 file The path name of a file containing the output of uuencode. 

38540 STDIN 

38541 See the INPUT FILES section. 


38542 INPUT FILES 

38543 The input files shall be files containing the output of uuencode. 


38544 ENVIRONMENT VARIABLES 

38545 The following environment variables shall affect the execution of uudecode: 


38546 

38547 

38548 

38549 

38550 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


38551 

38552 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


38553 

38554 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
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38555 arguments and input files). 

38556 LC_MESSAGES 

38557 Determine the locale that should be used to affect the format and contents of 

38558 diagnostic messages written to standard error. 

38559 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

38560 ASYNCHRONOUS EVENTS 

38561 Default. 

38562 STDOUT 

38563 If the file data header encoded by uuencode is - or /dev/stdout, or the -o /dev/stdout option I 

38564 overrides the file data, the standard output shall be in the same format as the file originally I 

38565 encoded by uuencode. Otherwise, the standard output shall not be used. I 

38566 STDERR 

38567 Used only for diagnostic messages. 

38568 OUTPUT FILES 

38569 The output file shall be in the same format as the file originally encoded by uuencode. 

38570 EXTENDED DESCRIPTION 

38571 None. 

38572 EXIT STATUS 

38573 The following exit values shall be returned: 

38574 0 Successful completion. 

38575 >0 An error occurred. 

38576 CONSEQUENCES OF ERRORS 

38577 Default. 

38578 APPLICATION USAGE 

38579 The user who is invoking uudecode must have write permission on any file being created. 

38580 The output of uuencode is essentially an encoded bit stream that is not cognizant of byte 

38581 boundaries. It is possible that a 9-bit byte target machine can process input from an 8-bit source, 

38582 if it is aware of the requirement, but the reverse is unlikely to be satisfying. Of course, the only 

38583 data that is meaningful for such a transfer between architectures is generally character data. 

38584 Application writers should note that this utility need not be provided on systems that do not 

38585 support the User Portability Utilities option. 

38586 EXAMPLES 

38587 None. 

38588 RATIONALE 

38589 Input files are not necessarily text files, as stated by an early proposal. Although the uuencode 

38590 output is a text file, that output could have been wrapped within another file or mail message 

38591 that is not a text file. I 

38592 The -o option is not historical practice, but was added at the request of WG15 so that the user I 

38593 could override the target path name without having to edit the input data itself. I 

38594 In early drafts, the [-o outfile] option-argument allowed the use of - to mean standard output. I 

38595 The symbol - has only been used previously in IEEE Std. 1003.1-200x as a standard input I 

38596 indicator. The developers of the standard did not wish to overload the meaning of - in this I 

38597 manner. The /dev/stdout concept exists on most modem systems. The /dev/stdout syntax does I 
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38598 not refer to a new special file. It is just a magic cookie to specify standard output. 

38599 FUTURE DIRECTIONS 

38600 None. 

38601 SEE ALSO 

38602 mtencode 

38603 CHANGE HISTORY 

38604 First released in Issue 4. 

38605 Issue 6 

38606 This utility is now marked as part of the User Portability Utilities option. 

38607 The -o outfile option is added, as specified in the IEEE P1003.2b draft standard. 

38608 The normative text is reworded to avoid use of the term "must” for application requirements. 
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38609 NAME 

38610 uuencode — encode a binary file 

38611 SYNOPSIS 

38612 up uuencode [— m] [file] decode_pathname I 

38613 I 

38614 DESCRIPTION 

38615 The uuencode utility shall write an encoded version of the named input file, or standard input if 

38616 no file is specified, to standard output. The output shall be encoded using one of the algorithms I 

38617 described in the STDOUT section and shall include the file access permission bits (in chmod octal I 

38618 or symbolic notation) of the input file and the decodejpatlmame, for re-creation of the file on 

38619 another system that conforms to this volume of IEEE Std. 1003.1-200x. 

38620 OPTIONS 

38621 The uuencode utility shall conform to the System Interface Definitions volume of I 

38622 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

38623 The following option shall be supported by the implementation: I 

38624 -m Encode the output using the MIME Base64 algorithm described below. If -m is not I 

38625 specified, the historical algorithm described in STDOUT shall be used. I 

38626 OPERANDS I 

38627 The following operands shall be supported: 

38628 decode_pathname 

38629 The path name of the file into which the nndecode utility shall place the decoded I 

38630 file. Specifying a decodejpathname operand of /dev/stdout shall indicate that I 

38631 nndecode is to use standard output. If there are characters in decode_pathname that I 

38632 are not in the portable file name character set the results are unspecified. 

38633 file A path name of the file to be encoded. 

38634 STDIN 

38635 See the INPUT FILES section. 


38636 INPUT FILES 

38637 Input files can be files of any type. 


38638 ENVIRONMENT VARIABLES 

38639 The following environment variables shall affect the execution of uuencode : 


38640 

38641 

38642 

38643 

38644 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


38645 LC_ALL If set to a non-empty string value, override the values of all the other 

38646 internationalization variables. 


38647 

38648 

38649 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


38650 LC_MESSAGES 

38651 Determine the locale that should be used to affect the format and contents of 

38652 diagnostic messages written to standard error. 
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38653 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

38654 ASYNCHRONOUS EVENTS 

38655 Default. 

38656 STDOUT 

38657 uuencode Base64 Algorithm I 

38658 The standard output shall be a text file (encoded in the character set of the current locale) that I 

38659 begins with the line: 

38660 "begin-base64ss\n" , <mode >, decode_pathname 

38661 and ends with the line: I 

38662 "====\n" I 

38663 In both cases, the lines shall have no preceding or trailing <blank>s. I 

38664 The encoding process represents 24-bit groups of input bits as output strings of four encoded I 

38665 characters. Preceding from left to right, a 24-bit input group shall be formed by concatenating I 

38666 three 8-bit input groups. These 24-bit then shall be treated as four concatenated 6-bit groups, I 

38667 each of which shall be translated into a single digit in the base64 alphabet. When encoding a bit I 

38668 stream via the base64 encoding, the bit stream shall be presumed to be ordered with the most- I 

38669 significant bit first. That is, the first bit in the stream shall be the high-order bit in the first byte, I 

38670 and the eighth bit shall be the low-order bit in the first byte, and so on. Each 6-bit group is used I 

38671 as an index into an array of 64 printable characters, as shown in Table 4-21. I 


38672 Table 4-21 uuencode Base64 Values 


38673 

Value 

Encoding 

Value 

Encoding 

Value 

Encoding 

Value 

Encoding 

38674 

0 

A 

17 

R 

34 

i 

51 

z 

38675 

1 

B 

18 

S 

35 

j 

52 

0 

38676 

2 

C 

19 

T 

36 

k 

53 

i 

38677 

3 

D 

20 

U 

37 

1 

54 

2 

38678 

4 

E 

21 

V 

38 

m 

55 

3 

38679 

5 

F 

22 

w 

39 

n 

56 

4 

38680 

6 

G 

23 

X 

40 

o 

57 

5 

38681 

7 

H 

24 

Y 

41 

p 

58 

6 

38682 

8 

I 

25 

Z 

42 

q 

59 

7 

38683 

9 

J 

26 

a 

43 

r 

60 

8 

38684 

10 

K 

27 

b 

44 

s 

61 

9 

38685 

11 

L 

28 

c 

45 

t 

62 

+ 

38686 

12 

M 

29 

d 

46 

u 

63 

/ 

38687 

13 

N 

30 

e 

47 

V 



38688 

14 

O 

31 

f 

48 

w 

(pad) 

= 

38689 

15 

P 

32 

g 

49 

X 



38690 

16 

Q 

33 

h 

50 

Y 




38691 The character referenced by the index shall be placed in the output string. 

38692 The output stream (encoded bytes) shall be represented in lines of no more than 76 characters 

38693 each. All line breaks or other characters not found in the table shall be ignored by decoding 

38694 software (see uudecode). 

38695 Special processing shall be performed if fewer than 24 bits are available at the end of a message 

38696 or encapsulated part of a message. A full encoding quantum shall always be completed at the 
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38697 

38698 

38699 

38700 

38701 

38702 

38703 

38704 

38705 

38706 

38707 

38708 

38709 

38710 

38711 

38712 

38713 

38714 

38715 

38716 

38717 

38718 

38719 

38720 

38721 

38722 

38723 

38724 

38725 

38726 

38727 

38728 

38729 

38730 

38731 

38732 

38733 

38734 

38735 

38736 

38737 


end of a message. When fewer than 24 input bits are available in an input group, zero bits shall 
be added (on the right) to form an integral number of 6-bit groups. Output character positions 
that are not required to represent actual input data shall be set to the character ' . Since all 

base64 input is an integral number of octets, only the following cases can arise: 

1. The final quantum of encoding input is an integral multiple of 24 bits; here, the final unit of 
encoded output shall be an integral multiple of 4 characters with no ' =' padding. 

2. The final quantum of encoding input is exactly 8 bits; here, the final unit of encoded output 
shall be two characters followed by two ' =' padding characters. 

3. The final quantum of encoding input is exactly 16 bits; here, the final unit of encoded 
output shall be three characters followed by one ' =' padding character. 

4. The terminating " ====" evaluates to nothing and denotes the end of the encoded data. 

uuencode Historical Algorithm 

The standard output shall be a text file (encoded in the character set of the current locale) that 
begins with the line: 

"beginA%sA%s\n" <mode>, <decode_pathname> 

and ends with the line: 

end\n 

In both cases, the lines shall have no preceding or trailing <blank> characters. 

The algorithm that shall be used for lines in between begin and end takes three octets as input 
and writes four characters of output by splitting the input at six-bit intervals into four octets, 
containing data in the lower six bits only. These octets shall be converted to characters by adding 
a value of 0x20 to each octet, so that each octet is in the range 0x20-0x5f, and then it shall be 
assumed to represent a printable character in the ISO/IEC 646:1991 standard encoded character 
set. It then shall be translated into the corresponding character codes for the codeset in use in the 
current locale. (For example, the octet 0x41, representing ' A', would be translated to ' A' in the 
current codeset, such as Oxcl if it were EBCDIC.) 

Where the bits of two octets are combined, the least significant bits of the first octet shall be 
shifted left and combined with the most significant bits of the second octet shifted right. Thus 
the three octets A, B,C shall be converted into the four octets: 

0x20 + (( A >> 2 ) & 0x3F) 

0x20 + (((A << 4) I ( (B >> 4) & OxF)) & 0x3F) 

0x20 + (((B « 2) | ((C >> 6) & 0x3)) & 0x3F) 

0x20 + (( C ) & 0x3F) 

These octets then shall be translated into the local character set. 

Each encoded line contains a length character, equal to the number of characters to be decoded 
plus 0x20 translated to the local character set as described above, followed by the encoded 
characters. The maximum number of octets to be encoded on each line shall be 45. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 
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38738 EXTENDED DESCRIPTION 

38739 None. 

38740 EXIT STATUS 

38741 The following exit values shall be returned: 

38742 0 Successful completion. 

38743 >0 An error occurred. 

38744 CONSEQUENCES OF ERRORS 

38745 Default. 

38746 APPLICATION USAGE 

38747 The file is expanded by 35 percent (each three octets become four, plus control information) 

38748 causing it to take longer to transmit. 

38749 Since this utility is intended to create files to be used for data interchange between systems with 

38750 possibly different codesets, and to represent binary data as a text file, the ISO/IEC 646:1991 

38751 standard was chosen for a midpoint in the algorithm as a known reference point. The output 

38752 from uuencode is a text file on the local system. If the output were in the ISO/IEC 646:1991 

38753 standard codeset, it might not be a text file (at least because the <newline> characters might not 

38754 match), and the goal of creating a text file would be defeated. If this text file was then carried to 

38755 another machine with the same codeset, it would be perfectly compatible with that system's 

38756 uudecode. If it was transmitted over a mail system or sent to a machine with a different codeset, 

38757 it is assumed that, as for every other text file, some translation mechanism would convert it (by 

38758 the time it reached a user on the other system) into an appropriate codeset. This translation only 

38759 makes sense from the local codeset, not if the file has been put into a ISO/IEC 646:1991 standard 

38760 representation first. Similarly, files processed by uuencode can be placed in pax archives, 

38761 intermixed with other text files in the same codeset. 

38762 The algorithm is described in terms of 8-bit quantities, or octets. Since no byte alignment is 

38763 implied, it encodes data from machines with any number of bits per byte. However, unless that 

38764 encoded data is then decoded on a machine with the same number of bits per byte, the output 

38765 might not be useful. 

38766 Application writers should note that this utility need not be provided on systems that do not 

38767 support the User Portability Utilities option. 

38768 EXAMPLES 

38769 None. 

38770 RATIONALE 

38771 A new algorithm was added at the request of the international community to parallel work in 

38772 RFC 2045 (MIME). As with the historical uuencode format, the Base64 Content-Transfer-Encoding 

38773 is designed to represent arbitrary sequences of octets in a form that is not humanly readable. A 

38774 65-character subset of the ISO/IEC 646:1991 standard is used, enabling 6 bits to be represented 

38775 per printable character. (The extra 65th character, ' =', is used to signify a special processing 

38776 function.) 

38777 This subset has the important property that it is represented identically in all versions of the 

38778 ISO/IEC 646:1991 standard, including US ASCII, and all characters in the subset are also 

38779 represented identically in all versions of EBCDIC. The historical uuencode algorithm does not 

38780 share this property, which is the reason that a second algorithm was added to the ISO POSIX-2 

38781 standard. 

38782 The string "====" was used for the termination instead of the end used in the original format 

38783 because the latter is a string that could be valid encoded input. 
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38784 In an early draft, the -m option was named -b (for Base64), but it was renamed to reflect its I 

38785 relationship to the RFC 2045. A -u was also present to invoke the default algorithm, but since I 

38786 this was not historical practice, it was omitted as being unnecessary. I 

38787 See the RATIONALE section in mtdecode for the derivation of the /dev/stdout symbol. I 

38788 FUTURE DIRECTIONS 

38789 None. 

38790 SEE ALSO 

38791 mailx, mtdecode 

38792 CHANGE HISTORY 

38793 First released in Issue 4. 


38794 Issue 6 

38795 This utility is now marked as part of the User Portability Utilities option. 


38796 The Base64 algorithm and the ability to output to /dev/stdout are added as specified in the 

38797 IEEE P1003.2b draft standard. 
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38798 NAME 

38799 uustat — uucp status inquiry and job control 

38800 SYNOPSIS 

38801 UN xsi uustat [ —q | —k jobid | -r jobid ] 

38802 xsi uustat [—s system] [—u user ] 

38803 DESCRIPTION 

38804 The uustat utility shall display the status of, or cancel, previously specified uucp requests, or 

38805 provide general status on uucp connections to other systems. 

38806 When no options are given, uustat shall write to standard output the status of all uucp requests 

38807 issued by the current user. 

38808 Typical implementations of this utility require a communications line configured to use the I 

38809 System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 

38810 Interface, but other communications means may be used. On systems where there are no I 

38811 available communications means (either temporarily or permanently), this utility shall write an 

38812 error message describing the problem and exits with a non-zero exit status. 

38813 OPTIONS 

38814 The uustat utility shall conform to the System Interface Definitions volume of I 

38815 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

38816 The following options shall be supported: 

38817 un -q Write the jobs queued for each machine. 

38818 -k jobid Kill the uucp request whose job identification is jobid. The application shall ensure I 

38819 that the killed uucp request belongs to the person invoking uustat unless that user I 

38820 has appropriate privileges. 

38821 -r jobid Rejuvenate jobid. The files associated with jobid are touched so that their 

38822 modification time is set to the current time. This prevents the cleanup program 

38823 from deleting the job until the jobs modification time reaches the limit imposed by 

38824 the program. 

38825 -s system Write the status of all uucp requests for remote system system. 

38826 -u user Write the status of all uucp requests issued by user. 

38827 OPERANDS 

38828 None. 

38829 STDIN 

38830 Not used. 

38831 INPUT FILES 

38832 None. 

38833 ENVIRONMENT VARIABLES 

38834 The following environment variables shall affect the execution of uustat: 

38835 LANG Provide a default value for the internationalization variables that are unset or null. 

38836 If LANG is unset or null, the corresponding value from the implementation- 

38837 dependent default locale shall be used. If any of the internationalization variables 

38838 contains an invalid setting, the utility shall behave as if none of the variables had 

38839 been defined. 
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38840 LC_ALL If set to a non-empty string value, override the values of all the other 

38841 internationalization variables. 

38842 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

38843 characters (for example, single-byte as opposed to multi-byte characters in 

38844 arguments). 

38845 LC_MESSAGES 

38846 Determine the locale that should be used to affect the format and contents of 

38847 diagnostic messages written to standard error, and informative messages written 

38848 to standard output. 

38849 LC_TIME Determine the format of date and time strings output by uustat. 

38850 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

38851 TZ Determine the timezone used with date and time strings. 

38852 ASYNCHRONOUS EVENTS 

38853 Default. 

38854 STDOUT 

38855 The standard output shall consist of information about each job selected, in an unspecified 

38856 format. The information shall include at least the job ID, the user ID or name, and the remote 

38857 system name. 

38858 STDERR 

38859 Used only for diagnostic messages. 

38860 OUTPUT FILES 

38861 None. 

38862 EXTENDED DESCRIPTION 

38863 None. 

38864 EXIT STATUS 

38865 The following exit values shall be returned: 

38866 0 Successful completion. 

38867 >0 An error occurred. 

38868 CONSEQUENCES OF ERRORS 

38869 Default. 

38870 APPLICATION USAGE 

38871 None. 

38872 EXAMPLES 

38873 None. 

38874 RATIONALE 

38875 None. 

38876 FUTURE DIRECTIONS 

38877 None. 

38878 SEE ALSO 

38879 liucp 
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38880 CHANGE HISTORY 

38881 First released in Issue 2. 

38882 Issue 4 

38883 Format reorganized. 

38884 Utility Syntax Guidelines support mandated. 

38885 Internationalized environment variable support mandated. 

38886 Presence of the utility mandated, even on systems where no communications are available. 

38887 Issue 6 

38888 The normative text is reworded to avoid use of the term "must” for application requirements. 
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38889 NAME 

38890 uux — remote command execution 

38891 SYNOPSIS 

38892 xsi uux [— np] command—string 

38893 UN xsi uux [—jnp] command—string 

38894 DESCRIPTION 

38895 The mix utility shall gather zero or more files from various systems, execute a shell pipeline (see 

38896 Section 2.9 on page 67) on a specified system, and then send the standard output of the 

38897 command to a file on a specified system. Only the first command of a pipeline can have a 

38898 system-name\ prefix. All other commands in the pipeline shall be executed on the system of the 

38899 first command. 

38900 The following restrictions are applicable to the shell pipeline processed by uux: 

38901 • In gathering files from different systems, path name expansion is not performed by uux. 

38902 Thus, a request such as: 

38903 uux "c8 9 remsys!'/*.c" 

38904 would attempt to copy the file named literally *.c to the local system. 

38905 • The redirection operators ">>", "<<", "> | ",and ">&" cannot be used. 

38906 • The reserved word ! cannot be used at the head of the pipeline to modify the exit status. 

38907 • Alias substitution is not performed. 

38908 A file name can be specified as for uucp; it can be an absolute path name, a path name preceded 

38909 by ~ name (which is replaced by the corresponding login directory), a path name specified as 

38910 ~/iest(dest is prefixed by the public directory called PUBDIR; the actual location of PUBDIR is 

38911 implementation-dependent), or a simple file name (which is prefixed by uux with the current 

38912 directory). See uucp on page 1008 for the details. 

38913 The execution of commands on remote systems shall take place in an execution directory known 

38914 to the uucp system. All files required for the execution shall be put into this directory unless they 

38915 already reside on that machine. Therefore, the application shall ensure that non-local file names I 

38916 (without path or machine reference) are unique within the uux request. I 

38917 The uux utility shall attempt to get all files to the execution system. For files that are output files, I 

38918 the application shall ensure that the file name is escaped using parentheses. I 

38919 The remote system shall notify the user by mail if the requested command on the remote system 

38920 was disallowed or the files were not accessible. This notification can be turned off by the -n 

38921 option. 

38922 Typical implementations of this utility require a communications line configured to use the I 

38923 System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 

38924 Interface, but other communications means may be used. On systems where there are no I 

38925 available communications means (either temporarily or permanently), this utility shall write an 

38926 error message describing the problem and exits with a non-zero exit status. 

38927 The uux utility cannot guarantee support for all character encodings in all circumstances. For 

38928 example, transmission data may be restricted to 7 bits by the underlying network, 8-bit data and 

38929 file names need not be portable to non-intemationalized systems, and so on. Under these 

38930 circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 

38931 standard International Reference Version (equivalent to ASCII) 7-bit range of characters be used 

38932 and that only characters defined in the Portable File Name Character Set be used for naming 
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38933 

38934 

38935 

38936 

38937 

38938 

38939 

38940 

38941 

38942 

38943 

38944 

38945 

38946 

38947 

38948 

38949 

38950 

38951 

38952 

38953 

38954 

38955 

38956 

38957 

38958 

38959 

38960 

38961 

38962 

38963 

38964 

38965 

38966 

38967 

38968 

38969 

38970 

38971 

38972 

38973 

38974 


files. 

OPTIONS 

The uux utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

-p Make the standard input to uux the standard input to the command-string. 

UN -j Write the job identification string to standard output. This job identification can be 

used by uustat to obtain the status or terminate a job. 

-n Do not notify the user if the command fails. 

OPERANDS 

The following operand shall be supported: 
command-string 

A string made up of one or more arguments that are similar to normal command 
arguments, except that the command and any file names can be prefixed by 
system-namel. A null system-name shall be interpreted as the local system. 

STDIN 

The standard input shall not be used unless the ' - ' or -p option is specified; in those cases, the 
standard input shall be made the standard input of the command-string. 

INPUT FILES 

Input files shall be selected according to the contents of command-string. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of uux: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

The standard output shall be not used unless the -j option is specified; in that case, the job 
identification string shall be written to standard output in the following format: 

"%s\n", <jobid> 
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38975 

38976 

38977 

38978 

38979 

38980 

38981 

38982 

38983 

38984 

38985 

38986 

38987 

38988 

38989 

38990 

38991 

38992 

38993 

38994 

38995 

38996 

38997 

38998 

38999 

39000 

39001 

39002 

39003 

39004 

39005 

39006 

39007 

39008 

39009 

39010 

39011 

39012 

39013 


STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

Output files shall be created or written, or both, according to the contents of command-string. 

If the -n is not used, mail files shall be modified following any command or file-access failures 
on the remote system. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

Note that, for security reasons, many installations limit the list of commands executable on 
behalf of an incoming request from mix. Many sites permit little more than the receipt of mail 
via mix. 

Any characters special to the command interpreter should be quoted either by quoting the entire 
command-string or quoting the special characters as individual arguments. 

As noted in uucp, shell pattern matching notation characters appearing in path names are 
expanded on the appropriate local system. This is done under the control of local settings of 
LCJZOLLATE and LC_CTYPE. Thus, care should be taken when using bracketed file name 
patterns, as collation and typing rules may vary from one system to another. Also be aware that 
certain types of expression (that is, equivalence classes, character classes, and collating symbols) 
need not be supported on non-intemationalized systems. 

EXAMPLES 

1. The following command gets filel from system a and file2 file from system b, executes diff 
on the local system, and puts the results in file.diff in the local PUBDIR directory. 
(PUBDIR is the uucp public directory on the local system.) 

uux "!diff a!/usr/filel b!/a4/file2 >!~/file.diff" 

2. The following command fails because uux places all files copied to a system in the same 
working directory. Although the files xyz are from two different systems, their file names 
are the same and conflict. 

uux "Idiff a!/usrl/xyz b!/usr2/xyz > ! ~/xyz.diff" 

3. The following command succeeds (assuming diff is permitted on system a) because the file 
local to system a is not copied to the working directory, and hence does not conflict the file 
from system c. 

uux "aldiff a!/usr/xyz c!/usr/xyz >!~/xyz.diff" 
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39014 RATIONALE 

39015 None. 

39016 FUTURE DIRECTIONS 

39017 A version of uux that fully supports the System Interface Definitions volume of I 

39018 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines may be introduced in a future I 

39019 issue. I 

39020 SEE ALSO 

39021 uucp, intencode, uustat 

39022 CHANGE HISTORY 

39023 First released in Issue 2. 

39024 Issue 4 

39025 Format reorganized. 

39026 Exceptions to Utility Syntax Guidelines conformance noted. 

39027 Internationalized environment variable support mandated. 

39028 Presence of the utility mandated, even on systems where no communications are available. 

39029 Issue 6 

39030 The obsolescent SYNOPSIS is removed. I 

39031 The normative text is reworded to avoid use of the term "must” for application requirements. I 
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39032 NAME 

39033 val — validate SCCS files (DEVELOPMENT) 

39034 SYNOPSIS 

39035 xsi val - 

39036 val [—s] [-m name ] [—r SID ] [—y type ] file. . . 

39037 


39038 DESCRIPTION 

39039 The val utility shall determine whether the specified file is an SCCS file meeting the 

39040 characteristics specified by the options. 


39041 OPTIONS 

39042 The val utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

39043 Section 12.2, Utility Syntax Guidelines, except that the usage of the ' operand is not strictly as I 

39044 intended by the guidelines (that is, reading options and operands from standard input). 


39045 The following options shall be supported: 


39046 -m name Specify a name , which is compared with the SCCS %M% keyword in file; see get on 

39047 page 510. 


39048 

39049 

39050 

39051 

39052 

39053 


-r SID Specify a SID (SCCS Identification String), an SCCS delta number. A check is made 

to determine if the SID is ambiguous (for example, -r 1 is ambiguous because it 
physically does not exist but implies 1.1,1.2, and so on, which may exist) or invalid 
(for example, -r 1.0 or -r 1.1.0 are invalid because neither case can exist as a valid 
delta number). If the SID is valid and not ambiguous, a check is made to 
determine whether it actually exists. 


39054 -s Silence the diagnostic message normally written to standard output for any error 

39055 that is detected while processing each named file on a given command line. 


39056 -y type Specify a type, which is compared with the SCCS %Y% keyword in file; see get on 

39057 page 510. 


39058 OPERANDS 

39059 The following operands shall be supported: 


39060 file 

39061 

39062 

39063 

39064 


A path name of an existing SCCS file. If a single instance file is specified as ' - ', 
and if no options are specified, the standard input shall be read: each line is I 
independently processed as if it were a command line argument list. (However, I 
the line is not subjected to any of the shell word expansions, such as parameter 
expansion or quote removal.) 


39065 STDIN 

39066 The standard input is a text file used only when the file operand is specified as ' - '. 


39067 INPUT FILES 

39068 Any SCCS files processed are files of an unspecified format. 


39069 ENVIRONMENT VARIABLES 

39070 The following environment variables shall affect the execution of val: 

39071 LANG Provide a default value for the internationalization variables that are unset or null. 

39072 If LANG is unset or null, the corresponding value from the implementation- 

39073 dependent default locale shall be used. If any of the internationalization variables 

39074 contains an invalid setting, the utility shall behave as if none of the variables had 

39075 been defined. 
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39076 LC_ALL If set to a non-empty string value, override the values of all the other 

39077 internationalization variables. 

39078 LCJCTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

39079 characters (for example, single-byte as opposed to multi-byte characters in 

39080 arguments and input files). 

39081 LC_MESSAGES 

39082 Determine the locale that should be used to affect the format and contents of 

39083 diagnostic messages written to standard error, and informative messages written 

39084 to standard output. 

39085 NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

39086 ASYNCHRONOUS EVENTS 

39087 Default. 

39088 STDOUT 

39089 The standard output shall consist of informative messages about either: 

39090 1. Each file processed 

39091 2. Each command line read from standard input 

39092 If the standard input is not used, for each file operand yielding a discrepancy, the output line 

39093 shall have the following format: 

39094 "%s: %s\n", <pathname>, <unspecified string> 

39095 If standard input is used, a line of input shall be written before each of the preceding lines for 

39096 files containing discrepancies: 

39097 "%s : \n" , <input line> 

39098 STDERR 

39099 Not used. 

39100 OUTPUT FILES 

39101 None. 

39102 EXTENDED DESCRIPTION 

39103 None. 

39104 EXIT STATUS 

39105 The 8-bit code returned by val is a disjunction of the possible errors, that is, it can be interpreted 

39106 as a bit string where set bits are interpreted as follows: 


39107 

0x80 

= Missing file argument. 

39108 

0x40 

= Unknown or duplicate option. 

39109 

0x20 

= Corrupted SCCS file. 

39110 

0x10 

= Cannot open file or file not SCCS. 

39111 

0x08 

= SID is invalid or ambiguous. 

39112 

0x04 

= SID does not exist. 

39113 

0x02 

= %Y%, -y mismatch. 

39114 

0x01 

= %M%, -m mismatch. 


39115 Note that val can process two or more files on a given command line and can process multiple 

39116 command lines (when reading the standard input). In these cases an aggregate code shall be 

39117 returned: a logical OR of the codes generated for each command line and file processed. 
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39118 CONSEQUENCES OF ERRORS 

39119 Default. 

39120 APPLICATION USAGE 

39121 Since the val exit status sets the 0x80 bit, shell applications checking "$?" cannot tell if it 

39122 terminated due to a missing file argument or receipt of a signal. 

39123 EXAMPLES 

39124 In a directory with three SCCS files, s.x (of t type "text"), s.y, and s.z (a corrupted file), the 

39125 following command could produce the output shown: 

39126 val - <<EOF 

39127 —y source s.x 

39128 -m y s.y 

39129 s . z 

39130 EOF 

39131 —y source s.x 

39132 s.x: %Y%, —y mismatch 

39133 s . z 

39134 s.z: corrupted SCCS file 

39135 RATIONALE 

39136 None. 

39137 FUTURE DIRECTIONS 

39138 None. 

39139 SEE ALSO 

39140 admin, delta, get, prs 

39141 CHANGE HISTORY 

39142 First released in Issue 2. 

39143 Issue 4 

39144 Format reorganized. 

39145 Exceptions to Utility Syntax Guidelines conformance noted. 

39146 Internationalized environment variable support mandated. 

39147 Issue 6 

39148 The Open Group corrigenda item U025/4 has been applied, correcting a typographical error in 

39149 the EXIT STATUS. 
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39150 NAME 

39151 vi — screen-oriented (visual) display editor 

39152 SYNOPSIS 

39153 UP vi [—rR] [-1] [—c command] [—t tagstring] [—w size] [file . . .] I 

39154 I 

39155 DESCRIPTION 

39156 Notes to Reviewers 

39157 This section zvith side shading zvill not appear in the final copy. - Ed. 

39158 This utility has undergone significant revision due to the 1003.2b merger. The following D1 I 

39159 XCU ERNs need to be checked after the merge: 361,363,364,366. I 

39160 This utility shall be provided on systems that both support the User Portability Utilities option 

39161 and define the POSIX2_CHAR_TERM symbol. On other systems it is optional. 

39162 The vi (visual) utility is a screen-oriented text editor. Only the open and visual modes of the I 

39163 editor are described in IEEE Std. 1003.1-200x; see the line editor ex for additional editing I 

39164 capabilities used in vi. The user can switch back and forth between vi and ex and execute ex I 

39165 commands from within vi. 

39166 This reference page uses the term edit buffer to describe the current working text. No specific I 

39167 implementation is implied by this term. All editing changes are performed on the edit buffer, I 

39168 and no changes to it shall affect any file until an editor command writes the file. I 

39169 When using vi, the terminal screen acts as a window into the editing buffer. Changes made to I 

39170 the editing buffer shall be reflected in the screen display; the position of the cursor on the screen 

39171 shall indicate the position within the editing buffer. 

39172 Certain terminals do not have all the capabilities necessary to support the complete vi definition. I 

39173 When these commands cannot be supported on such terminals, this condition shall not produce 

39174 an error message such as "not an editor command" or report a syntax error. The implementation 

39175 may either accept the commands and produce results on the screen that are the result of an 

39176 unsuccessful attempt to meet the requirements of this volume of IEEE Std. 1003.1-200x or report 

39177 an error describing the terminal-related deficiency. 

39178 OPTIONS 

39179 The vi utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

39180 Section 12.2, Utility Syntax Guidelines. I 

39181 The following options shall be supported: 

39182 -c command See the ex command description of the -c option. I 

39183 man -1 (The letter ell.) Set lisp mode; see Edit Options in ex on page 425. I 

39184 -r See the ex command description of the -r option. I 

39185 -R See the ex command description of the -R option. I 

39186 -t tagstring See the ex command description of the -t option. I 

39187 -w size See the ex command description of the -w option. I 

39188 OPERANDS I 

39189 See the OPERANDS section of the ex command for a description of the operands supported by I 

39190 the vi command. I 
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39191 

39192 

39193 

39194 

39195 

39196 

39197 

39198 

39199 

39200 

39201 

39202 

39203 

39204 

39205 

39206 

39207 

39208 

39209 

39210 

39211 

39212 

39213 

39214 

39215 

39216 

39217 

39218 

39219 

39220 

39221 

39222 

39223 

39224 

39225 

39226 

39227 

39228 

39229 

39230 

39231 

39232 

39233 


STDIN 

If standard input is not a terminal device, the results are undefined. The standard input consists 
of a series of commands and input text, as described in the EXTENDED DESCRIPTION section. 

If a read from the standard input returns an error, or if the editor detects an end-of-file condition 
from the standard input, it shall be equivalent to a SIGHUP asynchronous event. 

INPUT FILES 

See the INPUT FILES section of the ex command for a description of the input files supported by 
the vi command. 

ENVIRONMENT VARIABLES 

See the ENVIRONMENT VARIABLES section of the ex command for the environment variables 
that affect the execution of the vi command. 

ASYNCHRONOUS EVENTS 

See the ASYNCHRONOUS EVENTS section of the ex for the asynchronous events that affect the 
execution of the vi command. 

STDOUT 

If standard output is not a terminal device, undefined results occur. 

Standard output may be used for writing prompts to the user, for informational messages, and 
for writing lines from the file. 

STDERR 

If standard output is not a terminal device, undefined results occur. 

Used only for diagnostic messages. 

OUTPUT FILES 

See the OUTPUT FILES section of the ex command for a description of the output files 
supported by the vi command. 

EXTENDED DESCRIPTION 

If the terminal does not have the capabilities necessary to support an unspecified portion of the 
vi definition, implementations shall start initially in ex mode or open mode. Otherwise, after 
initialization, vi shall be in command mode; text input mode can be entered by one of several 
commands used to insert or change text. In text input mode, <ESC> can be used to return to 
command mode; other uses of <ESC> are described later in this section; see Terminate 
Command or Input Mode on page 1039. 

Initialization in ex and vi 

See Initialization in ex and vi on page 392 for a description of ex and vi initialization for the vi 
utility. 

Command Descriptions in vi 

The following symbols are used in this reference page to represent arguments to commands. 

buffer See the description of buffer in the EXTENDED DESCRIPTION section of the ex utility; 
see Command Descriptions in ex on page 401. 

In open and visual mode, when a command synopsis shows both [ buffer ] and [count] 
preceding the command name, they can be specified in either order. 

count A positive integer used as an optional argument to most commands, either to give a 
repeat count or as a size. This argument is optional and shall default to 1 unless 
otherwise specified. 
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39234 

39235 

39236 

39237 

39238 

39239 

39240 

39241 

39242 

39243 

39244 

39245 

39246 

39247 

39248 

39249 

39250 

39251 

39252 

39253 

39254 

39255 

39256 

39257 

39258 

39259 

39260 

39261 

39262 

39263 

39264 

39265 

39266 

39267 

39268 

39269 

39270 

39271 

39272 

39273 

39274 

39275 

39276 

39277 

39278 


The Synopsis lines for the vi commands <control>-G, <control>-L, <control>-R, 
<control>-], %, &, ", D, m, M, Q, u, U, and ZZ do not have count as an optional 
argument. Regardless, it shall not be an error to specify a count to these commands, and 
any specified count shall be ignored. 

motion An optional trailing argument used by the !, <, >, c, d, and y commands, which is used 
to indicate the region of text that shall be affected by the command. The motion can be 
either one of the command characters repeated or one of several other vi commands 
(listed in the following table). Each of the applicable commands specifies the region of 
text matched by repeating the command; each command that can be used as a motion 
command specifies the region of text it affects. 

Commands that take motion arguments operate on either lines or characters, depending 
on the circumstances. When operating on lines, all lines that fall partially or wholly 
within the text region specified for the command shall be affected. When operating on 
characters, only the exact characters in the specified text region shall be affected. Each 
motion command specifies this individually. 

When commands that may be motion commands are not used as motion commands, 
they shall set the current position to the current line and column as specified. 

The following commands shall be valid cursor motion commands: 


<control>-H 

f 

'character 

<newline> 

? 

b 

<carriage-return> 

B 

e 

<control>-N 

E 

f 

<control>-P 

F 

h 

<space> 

G 

j 

$ 

H 

k 

% 

L 

1 

'character 

M 

n 

( 

N 

t 

) 

T 

w 

+ 

W 

i 

/ 

[[ 

i 

- 

]] 

i 

/ 

A 

0 


Any count that is specified to a command that has an associated motion command shall 
be applied to the motion command. If a count is applied to both the command and its 
associated motion command, the effect shall be multiplicative. 

The following symbol is used in this section to specify locations in the edit buffer: 

current character 

The character that is currently displayed by the cursor. 

The following symbols are used in this section to specify command actions: 
bigzvord In the POSIX locale, vi shall recognize four kinds of bigzvords: 

1. A maximal sequence of non-<blank> characters preceded and followed by 
<blank> characters or the beginning or end of a line or the edit buffer 

2. One or more sequential empty or <blank> character-filled lines 
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39279 

39280 

39281 

39282 

39283 

39284 

39285 

39286 

39287 

39288 

39289 

39290 

39291 

39292 

39293 

39294 

39295 

39296 

39297 

39298 

39299 

39300 

39301 

39302 

39303 

39304 

39305 

39306 

39307 

39308 

39309 

39310 

39311 

39312 

39313 

39314 

39315 

39316 

39317 


3. The first character in the edit buffer 

4. The last character in the edit buffer 

word In the POSIX locale, vi shall recognize five kinds of words: 

1. A maximal sequence of letters, digits, and underscores, delimited at both ends by: 
— Characters other than letters, digits, or underscores 

— The beginning or end of a line 
— The beginning or end of the edit buffer 

2. A maximal sequence of characters other than letters, digits, underscores, or 
<blank> characters, delimited at both ends by: 

— A letter, digit, underscore 

— <blank> characters 

— The beginning or end of a line 

— The beginning or end of the edit buffer 

3. One or more sequential empty or <blank> character-filled lines 

4. The first character in the edit buffer 

5. The last character in the edit buffer 
section boundary 

A section boundary is one of the following: 

1. A line whose first character is a <form-feed> character 

2. A line whose first character is an open curly brace (' {') 

3. A line whose first character is a period and whose second and third characters 
match a two-character pair in the sections edit option (see ed) 

4. A line whose first character is a period and whose only other character matches 
the first character of a two-character pair in the sections edit option, where the 
second character of the two-character pair is a <space> character 

5. The first line of the edit buffer 

6. The last line of the edit buffer if the last line of the edit buffer is empty or if it is a 
]] or } command; otherwise, the last character of the last line of the edit buffer 

paragraph boundary 

A paragraph boundary is one of the following: 

1. A section boundary 

2. A line whose first character is a period and whose second and third characters 
match a two-character pair in the paragraphs edit option (see ed) 

3. A line whose first character is a period and whose only other character matches 
the first character of a two-character pair in the paragraphs edit option, where the 
second character of the two-character pair is a <space> character 

4. One or more sequential empty or <blank> character-filled lines 
remembered search direction 

See the description of remembered search direction in ed. 
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39321 

39322 

39323 

39324 

39325 

39326 

39327 

39328 

39329 

39330 

39331 

39332 

39333 

39334 

39335 

39336 

39337 

39338 

39339 

39340 

39341 

39342 

39343 

39344 

39345 

39346 

39347 

39348 

39349 

39350 

39351 

39352 

39353 

39354 

39355 

39356 

39357 

39358 

39359 

39360 

39361 

39362 

39363 


vi Utilities 


sentence boundary 

A sentence boundary is one of the following: 

1. A paragraph boundary 

2. The first non-<blank> character that occurs after a paragraph boundary 

3. The first non-<blank> character that occurs after a period (' .'exclamation 

point (' !'), or question mark (' ?'), followed by two <space> characters or the 
end of a line; any number of closing parenthesis (')')/ closing brackets (']')/ 
double quote (' ) , ' or single quote (' ' ') characters can appear between the 

punctuation mark and the two <space> characters or end-of-line 

Any lines displayed on the screen that logically represent lines after the last line in the edit buffer 
shall consist of a single tilde (' ~') character. 

The last line of the screen shall be used to report errors or display informational messages. It 
shall also be used to display the input for "line-oriented commands" (/, ?,and !). When a line- 
oriented command is executed, the editor shall enter text input mode on the last line on the 
screen, using the respective command characters as prompt characters. (In the case of the ! 
command, the associated motion shall be entered by the user before the editor enters text input 
mode.) The line entered by the user shall be terminated by a character, a non-<control>-V- 
escaped <carriage-return> character, or unescaped <ESC>. It is unspecified if more characters 
than require a display width minus one column number of screen columns can be entered. 

If any command is executed that overwrites a portion of the screen other than the last line of the 
screen (for example, the ex suspend, or ! commands), other than the ex shell command, the user 
shall be prompted for a character before the screen is refreshed and the edit session continued. 

<tab> characters shall take up the number of columns on the screen set by the tabstop edit 
option (see ed), unless there are less than that number of columns before the display margin that 
will cause the displayed line to be folded; in this case, they shall only take up the number of 
columns up to that boundary. 

The cursor shall be placed on the current line and relative to the current column as specified by 
each command described in the following sections. 

In open mode, if the current line is not already displayed, then it shall be displayed. 

In visual mode, if the current line is not displayed, then the lines that are displayed shall be 
expanded, scrolled, or redrawn to cause an unspecified portion of the current line to be 
displayed. If the screen is redrawn, no more than the number of logical lines specified by the 
value of the window edit option shall be displayed (unless the current line cannot be completely 
displayed in the number of logical lines specified by the window edit option) and the current 
line shall be positioned as close to the center of the displayed lines as possible (within the 
constraints imposed by the distance of the line from the beginning or end of the edit buffer). If 
the current line is before the first line in the display and the screen is scrolled, an unspecified 
portion of the current line shall be placed on the first line of the display. If the current line is after 
the last line in the display and the screen is scrolled, an unspecified portion of the current line 
shall be placed on the last line of the display. 

In visual mode, if a line from the edit buffer (other than the current line) does not entirely fit into 
the lines at the bottom of the display that are available for its presentation, the editor may 
choose not to display any portion of the line. The lines of the display that do not contain text 
from the edit buffer for this reason shall each consist of a single ' @' character. 

In visual mode, the editor may choose for unspecified reasons to not update lines in the display 
to correspond to the underlying edit buffer text. The lines of the display that do not correctly 
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correspond to text from the edit buffer for this reason shall consist of a single ' @' character, and 
the <control>-R command shall cause the editor to update the screen to correctly represent the 
edit buffer. 

Open and visual mode commands that set the current column set it to a column position in the 
display, and not a character position in the line. In this case, however, the column position in the 
display shall be calculated for a infinite width display; for example, the column related to a 
character that is part of a line that has been folded onto additional screen lines will be offset from 
the screen column where the physical line begins, not from the beginning of a particular screen 
line. 

The physical cursor column in the display is based on the value of the current column, as 
follows, with each rule applied in turn: 

1. If the current column is after the last screen column used by the displayed line, the 
physical cursor column shall be set to the last screen column occupied by the last character 
in the current line; otherwise, the physical cursor column shall be set to the current 
column. 

2. If the character of which some portion is displayed in the screen column specified by the 
physical cursor column requires more than a single screen column: 

a. If in text input mode, the physical cursor column shall be adjusted to the first screen 
column in which any portion of that character is displayed. 

b. Otherwise, the physical cursor column shall be adjusted to the last screen column in 
which any portion of that character is displayed. 

The current column shall not be changed by these adjustments to the physical cursor column. 

If an error occurs during the parsing or execution of a vi command: 

• The terminal shall be alerted. Execution of the vi command shall stop, and the cursor (for 
example, the current line and column) shall not be further modified. 

• Unless otherwise specified by the following command sections, it is unspecified whether an 
informational message shall be displayed. 

• Any partially entered vi command shall be discarded. 

• If the vi command resulted from a map expansion, all characters from that map expansion 
shall be discarded, except as otherwise specified by the map command (see ed). 

• If the vi command resulted from the execution of a buffer, no further commands caused by 
the execution of the buffer shall be executed. 

Page Backwards 

Synopsis: [count] <control>-B 

If in open mode, the <control>-B command shall behave identically to the z command. 
Otherwise, if the current line is the first line of the edit buffer, it shall be an error. 

If the window edit option is less than 3, display a screen where the last line of the display shall 
be some portion of: 

(current first line) —1 

otherwise, display a screen where the first line of the display shall be some portion of: 

(current first line) —count W ((window edit option) —2) 
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If this calculation would result in a line that is before the first line of the edit buffer, the first line I 
of the display shall display some portion of the first line of the edit buffer. I 

Current line: If no lines from the previous display remain on the screen, set to the last line of the I 
display; otherwise, set to ( line - the number of new lines displayed on this screen). I 

Current column: Set to non-<blank>. I 

Scroll Forward 

Synopsis: [count] <control>-D 

If the current line is the last line of the edit buffer, it shall be an error. I 

If no count is specified, count shall default to the count associated with the previous <control>-D I 
or <control>-U command. If there was no previous <control>-D or <control>-U command, count I 
shall default to the value of the scroll edit option. I 

If in open mode, write lines starting with the line after the current line, until count lines or the I 
last line of the file have been written. I 

Current line: If the current line + count is past the last line of the edit buffer, set to the last line of I 
the edit buffer; otherwise, set to the current line + count. I 

Current column: Set to non-<blank>. I 

Scroll Forward by Line 

Synopsis: [count] <control>-E 

Display the line count lines after the last line currently displayed. I 

If the last line of the edit buffer is displayed, it shall be an error. If there is no line count lines I 
after the last line currently displayed, the last line of the display shall display some portion of I 
the last line of the edit buffer. I 

Current line: Unchanged if the previous current character is displayed; otherwise, set to the first I 
line displayed. I 

Current column: Unchanged. I 

Page Forward 

Synopsis: [count] <control>-F 

If in open mode, the <control>-F command shall behave identically to the z command. I 
Otherwise, if the current line is the last line of the edit buffer, it shall be an error. I 

If the window edit option is less than 3, display a screen where the first line of the display shall I 
be some portion of: I 

(current last line) +1 I 

otherwise, display a screen where the first line of the display shall be some portion of: I 

(current first line) + count W ((window edit option) —2) I 

If this calculation would result in a line that is after the last line of the edit buffer, the last line of I 
the display shall display some portion of the last line of the edit buffer. I 

Current line: If no lines from the previous display remain on the screen, set to the first line of the I 
display; otherwise, set to ( line + the number of new lines displayed on this screen). I 
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39443 Current column: Set to non-<blank>. 

39444 Display Information 

39445 Synopsis: <control>-G 

39446 This command shall be equivalent to the ex file command . 

39447 Move Cursor Backwards 

39448 Synopsis: [count] <control>-H 

39449 [count] h 

39450 the current erase character (see stty) 

39451 If there are no characters before the current character on the current line, it shall be an error. If 

39452 there are less than count previous characters on the current line, count shall be adjusted to the 

39453 number of previous characters on the line. 

39454 If used as a motion command: 

39455 1. The text region shall be from the character before the starting cursor up to and including 

39456 the count th character before the starting cursor. 

39457 2. Any text copied to a buffer shall be in character mode. 

39458 If not used as a motion command: 

39459 Current line: Unchanged. 

39460 Current column: Set to (column - the number of columns occupied by count characters ending 

39461 with the previous current column). 


39462 Move Down 


39463 

Synopsis: 

[count] 

<newline> 

39464 


[count] 

<control>-J 

39465 


[count] 

<control>-M 

39466 


[count] 

<control>-N 

39467 


[count] 

j 

39468 


[count] 

<carriage-return> 

39469 


[count] 

+ 


39470 If there are less than count lines after the current line in the edit buffer, it shall be an error. 

39471 If used as a motion command: 

39472 1. The text region shall include the starting line and the next count -1 lines. 

39473 2. Any text copied to a buffer shall be in line mode. 

39474 If not used as a motion command: 

39475 Current line: Set to current line + count. 

39476 Current column: Set to non-<blank> for the <carriage-return> character, <control>-M, and + 

39477 commands; otherwise, unchanged. 
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Clear and Redisplay 

Synopsis: <control>-L 

If in open mode, clear the screen and redisplay the current line. Otherwise, clear and redisplay 
the screen. 

Current line: Unchanged. 

Current column: Unchanged. 

Move Up 

Synopsis: [count] <control>-P 

[count] k 
[count] - 

If there are less than count lines before the current line in the edit buffer, it shall be an error. 

If used as a motion command: 

1. The text region shall include the starting line and the previous count lines. 

2. Any text copied to a buffer shall be in line mode. 

If not used as a motion command: 

Current line: Set to current line - count. 

Current column: Set to non-<blank> for the - command; otherwise, unchanged. 

Redraw Screen 

Synopsis: <control>-R 

If any lines have been deleted from the logical screen and flagged as deleted on the terminal 
using the @ convention (see the beginning of the EXTENDED DESCRIPTION section), they shall 
be redisplayed to match the contents of the edit buffer. 

It is unspecified whether lines flagged with @ because they do not fit on the terminal display 
shall be affected. 

Current line: Unchanged. 

Current column: Unchanged. 

Scroll Backward 

Synopsis: [count] <control>-U 

If the current line is the first line of the edit buffer, it shall be an error. 

If no count is specified, count shall default to the count associated with the previous <control>-D 
or <control>-U command. If there was no previous <control>-D or <control>-U command, count 
shall default to the value of the scroll edit option. 

Current line: If count is greater than the current line, set to 1; otherwise, set to the current line - 
count. 

Current column: Set to non-<blank>. 
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Scroll Backward by Line 

Synopsis: [count] <control>-Y 

Display the line count lines before the first line currently displayed. 

If the current line is the first line of the edit buffer, it shall be an error. If this calculation would 
result in a line that is before the first line of the edit buffer, the first line of the display shall 
display some portion of the first line of the edit buffer. 

Current line: Unchanged if the previous current character is displayed; otherwise, set to the first 
line displayed. 

Current column: Unchanged. 

Edit the Alternate File 

Synopsis: <control>-~ 

This command shall be equivalent to the ex edit command, with the alternate path name as its 
argument. 

Terminate Command or Input Mode 

Synopsis: <ESC> 

If a partial vi command (as defined by at least one, non -count character) has been entered, 
discard the count and the command character(s). 

Otherwise, if no command characters have been entered, and the <ESC> was the result of a map 
expansion, the terminal shall be alerted and the <ESC> character shall be discarded, but it shall 
not be an error. 

Otherwise, it shall be an error. 

Current line: Unchanged. 

Current column: Unchanged. 

Search for tagstring 

Synopsis: <control>-] 

If the current character is not a word or <blank> character, it shall be an error. 

This command shall be equivalent to the ex tag command, with the argument to that command 
defined as follows. 

If the current character is a <blank> character: 

1. Skip all <blank> characters after the cursor up to the end of the line. 

2. If the end of the line is reached, it shall be an error. 

Then, the argument to the ex tag command shall be the current character and all subsequent 
characters, up to the first non-word character or the end of the line. 
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Move Cursor Forward 

Synopsis: [ count ] <space> 

[count] 1 (ell) 

If there are less than count characters after the cursor on the current line, count shall be adjusted 
to the number of characters after the cursor on the line. 

If used as a motion command: 

1. If the current or count th character after the cursor is the last character in the line, the text 
region shall be comprised of the current character up to and including the last character in 
the line. Otherwise, the text region shall be from the current character up to, but not 
including, the count th character after the cursor. 

2. Any text copied to a buffer shall be in character mode. 

If not used as a motion command: 

If there are no characters after the current character on the current line, it shall be an error. 
Current line: Unchanged. 

Current column: Set to the last column that displays any portion of the count th character after the 
current character. 

Replace Text with Results from Shell Command 

Synopsis: [count] ! motion shell-commands <newline> 

If the motion command is the ! command repeated: 

1. If the edit buffer is empty and no count was supplied, the command shall be the equivalent 
of the ex :read ! command, with the text input, and no text shall be copied to any buffer. 

2. Otherwise: 

a. If there are less than count -1 lines after the current line in the edit buffer, it shall be 
an error. 

b. The text region shall be from the current line up to and including the next count -1 
lines. 

Otherwise, the text region shall be the lines in which any character of the text region specified by 
the motion command appear. 

Any text copied to a buffer shall be in line mode. 

This command shall be equivalent to the ex ! command for the specified lines. 

Move Cursor to End-of-line 

Synopsis: [count] $ 

It shall be an error if there are less than (count -1) lines after the current line in the edit buffer. 

If used as a motion command: 

1. If count is 1: 

a. It shall be an error if the line is empty. 

b. Otherwise, the text region shall consist of all characters from the starting cursor to 
the last character in the line, inclusive, and any text copied to a buffer shall be in 
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character mode. 

2. Otherwise, if the starting cursor position is at or before the first non-<blank> character in 
the line, the text region shall consist of the current and the next count -1 lines, and any text 
saved to a buffer shall be in line mode. 

3. Otherwise, the text region shall consist of all characters from the starting cursor to the last 
character in the line that is count -1 lines forward from the current line, and any text copied 
to a buffer shall be in character mode. 

If not used as a motion command: 

Current line : Set to the current line + count-1. 

Current column: The current column is set to the last screen column of the last character in the 
line, or column position 1 if the line is empty. 

The current column shall be adjusted to be on the last screen column of the last character of the 
current line as subsequent commands change the current line, until a command changes the 
current column. 

Move to Matching Character 

Synopsis: % 

If the character at the current position is not a parenthesis, bracket, or curly brace, search 
forwards in the line to the first one of those characters. If no such character is found, it shall be 
an error. 

The matching character shall be the parenthesis, bracket, or curly brace matching the 
parenthesis, bracket, or curly brace, respectively, that was at the current position or that was 
found on the current line. 

Matching shall be determined as follows, for an open parenthesis: 

1. Set a counter to 1. 

2. Search forwards until a parenthesis is found or the end of the edit buffer is reached. 

3. If the end of the edit buffer is reached, it shall be an error. 

4. If an open parenthesis is found, increment the counter by 1. 

5. If a close parenthesis is found, decrement the counter by 1. 

6. If the counter is zero, the current character is the matching character. 

Matching for a close parenthesis shall be equivalent, except that the search shall be backwards, 
from the starting character to the beginning of the buffer, a close parenthesis shall increment the 
counter by 1, and an open parenthesis shall decrement the counter by 1. 

Matching for brackets and curly braces shall be equivalent, except that searching shall be done 
for open and close brackets or open and close curly braces. It is implementation-dependent 
whether other characters are searched for and matched as well. 

If used as a motion command: 

1. If the matching cursor was after the starting cursor in the edit buffer, and the starting 
cursor position was at or before the first non-<blank> character in the starting line, and the 
matching cursor position was at or after the last non-<blank> character in the matching 
line, the text region shall consist of the current line to the matching line, inclusive, and any 
text copied to a buffer shall be in line mode. 
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2. If the matching cursor was before the starting cursor in the edit buffer, and the starting I 

cursor position was at or after the last non-<blank> character in the starting line, and the I 
matching cursor position was at or before the first non-<blank> character in the matching I 
line, the text region shall consist of the current line to the matching line, inclusive, and any I 
text copied to a buffer shall be in line mode. I 

3. Otherwise, the text region shall consist of the starting character to the matching character, I 

inclusive, and any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

Current line: Set to the line where the matching character is located. I 

Current column: Set to the last column where any portion of the matching character is displayed. I 

Repeat Substitution 

Synopsis: & 

Repeat the previous substitution command. This command shall be equivalent to the ex & I 
command with the current line as its addresses, and without options , count, or flags . I 

Return to Previous Context at Beginning of Line 

Synopsis: ' character 

It shall be an error if there is no line in the edit buffer marked by character. I 

If used as a motion command: I 

1. If the starting cursor is after the marked cursor, then the locations of the starting cursor I 

and the marked cursor in the edit buffer shall be logically swapped. I 

2. The text region shall consist of the starting line up to and including the marked line, and I 

any text copied to a buffer shall be in line mode. I 

If not used as a motion command: I 

Current line: Set to the line referenced by the mark. I 

Current column: Set to non-<blank>. I 

Return to Previous Context 

Synopsis: ' character 

It shall be an error if the marked line is no longer in the edit buffer. If the marked line no longer I 
contains a character in the saved numbered character position, it shall be as if the marked I 
position is the first non-<blank> character. I 

If used as a motion command: I 

1. It shall be an error if the marked cursor references the same character in the edit buffer as I 

the starting cursor. I 

2. If the starting cursor is after the marked cursor, then the locations of the starting cursor I 

and the marked cursor in the edit buffer shall be logically swapped. I 

3. If the starting line is empty or the starting cursor is at or before the first non-<blank> I 
character of the starting line, and the marked cursor line is empty or the marked cursor I 
references the first character of the marked cursor line, the text region shall consist of all I 
lines containing characters from the starting cursor to the line before the marked cursor I 
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line, inclusive, and any text copied to a buffer shall be in line mode. 

4. Otherwise, if the marked cursor line is empty or the marked cursor references a character 
at or before the first non-<blank> character of the marked cursor line, the region of text 
shall be from the starting cursor to the last character of the line before the marked cursor 
line, inclusive, and any text copied to a buffer shall be in character mode. 

5. Otherwise, the region of text shall be from the starting cursor (inclusive), to the marked 
cursor (exclusive), and any text copied to a buffer shall be in character mode. 

If not used as a motion command: 

Current line: Set to the line referenced by the mark. 

Current column: Set to the last column in which any portion of the character referenced by the 

mark is displayed. 

Return to Previous Section 

Synopsis: [ [ 

Move the cursor backward through the edit buffer to the first character of the previous section 

boundary, count times. 

If used as a motion command: 

1. If the starting cursor was at the first character of the starting line or the starting line was 
empty, and the first character of the boundary was the first character of the boundary line, 
the text region shall consist of the current line up to and including the line where the 
count th next boundary starts, and any text copied to a buffer shall be in line mode. 

2. If the boundary was the last line of the edit buffer or the last character of the last line of the 
edit buffer, the text region shall consist of the last character in the edit buffer up to and 
including the starting character, and any text saved to a buffer shall be in character mode. 

3. Otherwise, the text region shall consist of the starting character up to but not including the 
first character in the conntih next boundary, and any text copied to a buffer shall be in 
character mode. 


If the lisp option is set, a section boundary is also identified by a line with a leading ' ('. 

If not used as a motion command: 

Current line: Set to the line where the count th next boundary in the edit buffer starts. 

Current column: Set to the last column in which any portion of the first character of the conntih 

next boundary is displayed, or column position 1 if the line is empty. 

Move to Next Section 

Synopsis: ] ] 

Move the cursor forward through the edit buffer to the first character of the next section 

boundary, count times. 

If used as a motion command: 

1. If the starting cursor was at the first character of the starting line or the starting line was 
empty, and the first character of the boundary was the first character of the boundary line, 
the text region shall consist of the current line up to and including the line where the 
count th previous boundary starts, and any text copied to a buffer shall be in line mode. 
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2. If the boundary was the first line of the edit buffer, the text region shall consist of the first 
character in the edit buffer up to but not including the starting character, and any text 
copied to a buffer shall be in character mode. 

3. Otherwise, the text region shall consist of the first character in the count th previous section 
boundary up to but not including the starting character, and any text copied to a buffer 
shall be in character mode. 

man If the lisp option is set, a section boundary is also identified by a line with a leading ' (' • 

If not used as a motion command: 

Current line: Set to the line where the count th previous boundary in the edit buffer starts. 

Current column: Set to the last column in which any portion of the first character of the count th 

previous boundary is displayed, or column position 1 if the line is empty. 

Move to First Non-<blank> Position on Current Line 

Synopsis: A 

If used as a motion command: 

1. If the line has no non-<blank> characters, or if the cursor is at the first non-<blank> 
character of the line, it shall be an error. 

2. If the cursor is before the first non-<blank> character of the line, the text region shall be 
comprised of the current character, up to, but not including, the first non-<blank> 
character of the line. 

3. If the cursor is after the first non-<blank> character of the line, the text region shall be from 
the character before the starting cursor up to and including the first non-<blank> character 
of the line. 

4. Any text copied to a buffer shall be in character mode. 

If not used as a motion command: 

Current line: Unchanged. 

Current column: Set to non-<blank>. 

Current and line above 

Synopsis: [count] _ 

If there are less than count -1 lines after the current line in the edit buffer, it shall be an error. 

If used as a motion command: 

1. If count is less than 2, the text region shall be the current line. 

2. Otherwise, the text region shall include the starting line and the next count -1 lines. 

3. Any text copied to a buffer shall be in line mode. 

If not used as a motion command: 

Current line: Set to current line + count -1. 

Current column: Set to non-<blank>. 
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Move Back to Beginning of Sentence 

Synopsis: [count] ( 

Move backward to the beginning of a sentence. This command shall be equivalent to the [[ I 
command, with the exception that sentence boundaries shall be used instead of section I 
boundaries. I 

man If the lisp option is set, a lisp s-expression is considered a sentence for this command. I 

Move Forward to Beginning of Sentence 

Synopsis: [count] ) 

Move forward to the beginning of a sentence. This command shall be equivalent to the ]] I 
command, with the exception that sentence boundaries shall be used instead of section I 
boundaries. I 

man If the lisp option is set, a lisp s-expression is considered a sentence for this command. I 

Move Back to Preceding Paragraph 

Synopsis: [count] { 

Move back to the beginning of the preceding paragraph. This command shall be equivalent to I 
the [[ command, with the exception that paragraph boundaries shall be used instead of section I 
boundaries. I 

Move Forward to Next Paragraph 

Synopsis: [count] } 

Move forward to the beginning of the next paragraph. This command shall be equivalent to the I 
]] command, with the exception that paragraph boundaries shall be used instead of section I 
boundaries. I 

Move to Specific Column Position 

Synopsis: [count] | 

For the purposes of this command, lines that are too long for the current display and that have I 
been folded shall be treated as having a single, 1-based, number of columns. I 

If there are less than count columns in which characters from the current line are displayed on I 
the screen, count shall be adjusted to be the last column in which any portion of the line is I 
displayed on the screen. I 

If used as a motion character: I 

1. If the line is empty, or the cursor character is the same as the character on the count th I 

column of the line, it shall be an error. I 

2. If the cursor is before the countth column of the line, the text region shall be comprised of I 

the current character, up to but not including the character on the count th column of the I 
line. I 

3. If the cursor is after the count th column of the line, the text region shall be from the I 

character before the starting cursor up to and including the character on the countth I 
column of the line. I 


Commands and Utilities, Issue 6 


1045 




VI 


Utilities 


39778 

39779 

39780 

39781 

39782 

39783 

39784 

39785 

39786 

39787 

39788 

39789 

39790 

39791 

39792 

39793 

39794 

39795 

39796 

39797 

39798 

39799 

39800 

39801 

39802 

39803 

39804 

39805 

39806 

39807 

39808 

39809 

39810 

39811 

39812 

39813 

39814 

39815 

39816 


4. Any text copied to a buffer shall be in character mode. I 

If not used as a motion character: I 

Current line: Unchanged. I 

Current column: Set to the last column in which any portion of the character that is displayed in I 
the count column of the line is displayed. I 

Reverse Find Character 

Synopsis: [count] , 

If the last F, f, T, or t command was F, f, T, or t, this command shall be equivalent to an f, F, t, or I 
T command, respectively, with the specified count and the same search character. I 

If there was no previous F, f, T, or t command, it shall be an error. I 

Repeat 

Synopsis: [count] . 

Repeat the last!, <, >, A, C, D, I, J, O, P, R, S, X, Y, a, c, d, i, o, p, r, s, x, y, or ~ command. It shall I 
be an error if none of these commands have been executed. Commands (other than commands I 
that enter text input mode) executed as a result of map expansions, shall not change the value of I 
the last repeatable command. I 

Repeated commands with associated motion commands shall repeat the motion command as I 
well; however, any specified count shall replace the count(s) that were originally specified to the I 
repeated command or its associated motion command. I 

If the motion component of the repeated command is f, F, t, or T, the repeated command shall I 
not set the remembered search character for the; and, commands. I 

If the repeated command is p or P, and the buffer associated with that command was a numeric I 
buffer named with a number less than 9, the buffer associated with the repeated command shall I 
be set to be the buffer named by the name of the previous buffer logically incremented by 1. I 

If the repeated character is a text input command, the input text associated with that command I 
is repeated literally: I 

• Input characters are neither macro or abbreviation-expanded. I 

• Input characters are not interpreted in any special way with the exception that the <newline> I 

character and the <carriage-return> character, and <control>-T behave as described in Input I 
Mode Commands in vi on page 1064. I 

Current line: Set as described for the repeated command. I 

Current column: Set as described for the repeated command. I 

Find Regular Expression 

Synopsis: / I 

If the input line contains no characters, it shall be equivalent to a line containing only the last I 
regular expression encountered. The enhanced regular expressions supported by vi are I 
described in Regular Expressions in ex on page 424. I 

Otherwise, the line shall be interpreted as one or more regular expressions, optionally followed I 
by an address offset or a vi z command. I 
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If the regular expression is not the last regular expression on the line, or if a line offset or z 
command is specified, the regular expression shall be terminated by an unescaped ' /' 
character, which shall not be used as part of the regular expression. If the regular expression is 
not the first regular expression on the line, it shall be preceded by zero or more <blank> 
characters, a semicolon, zero or more <blank> characters, and a leading ' /' character, which 
shall not be interpreted as part of the regular expression. It shall be an error to precede any 
regular expression with any characters other than these. 

Each search shall begin from the character after the first character of the last match (or, if it is the 
first search, after the cursor). If the wrapscan edit option is set, the search shall continue to the 
character before the starting cursor character; otherwise, to the end of the edit buffer. It shall be 
an error if any search fails to find a match, and an informational message to this effect shall be 
displayed. 

An optional address offset (see Addressing in ex on page 394) can be specified after the last 
regular expression by including a trailing ' /' character after the regular expression and 
specifying the address offset. This offset will be from the line containing the match for the last 
regular expression specified. It shall be an error if the line offset would indicate a line address 
less than 1 or greater than the last line in the edit buffer. An address offset of zero shall be 
supported. It shall be an error to follow the address offset with any other characters than 
<blank> characters. 

If not used as a motion command, an optional z command (see Redraw Window on page 1063) 
can be specified after the last regular expression by including a trailing ' /' character after the 
regular expression, zero or more <blank> characters, a ' z', zero or more <blank> characters, an 
optional new window edit option value, zero or more <blank> characters, and a location 
character. The effect shall be as if the z command was executed after the / command. It shall be 
an error to follow the z command with any other characters than <blank> characters. 

The remembered search direction shall be set to forward. 

If used as a motion command: 

1. It shall be an error if the last match references the same character in the edit buffer as the 
starting cursor. 

2. If any address offset is specified, the last match shall be adjusted by the specified offset as 
described previously. 

3. If the starting cursor is after the last match, then the locations of the starting cursor and the 
last match in the edit buffer shall be logically swapped. 

4. If any address offset is specified, the text region shall consist of all lines containing 
characters from the starting cursor to the last match line, inclusive, and any text copied to a 
buffer shall be in line mode. 

5. Otherwise, if the starting line is empty or the starting cursor is at or before the first non- 
<blank> character of the starting line, and the last match line is empty or the last match 
starts at the first character of the last match line, the text region shall consist of all lines 
containing characters from the starting cursor to the line before the last match line, 
inclusive, and any text copied to a buffer shall be in line mode. 

6. Otherwise, if the last match line is empty or the last match begins at a character at or 
before the first non-<blank> of the last match line, the region of text shall be from the 
current cursor to the last character of the line before the last match line, inclusive, and any 
text copied to a buffer shall be in character mode. 
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39862 7. Otherwise, the region of text shall be from the current cursor (inclusive), to the first 

39863 character of the last match (exclusive), and any text copied to a buffer shall be be in 

39864 character mode. 

39865 If not used as a motion command: 

39866 Current line : If a match is found, set to the last matched line plus the address offset, if any; 

39867 otherwise, unchanged. 

39868 Current column: Set to the last column on which any portion of the first character in the last 

39869 matched string is displayed, if a match is found; otherwise, unchanged. 

39870 Move to First Character in Line 

39871 Synopsis: 0 (zero) 

39872 Move to the first character on the current line. The character ' 0 ' shall not be interpreted as a 

39873 command if it is immediately preceded by a digit. 

39874 If used as a motion command: 

39875 1. If the cursor character is the first character in the line, it shall be an error. 

39876 2. The text region shall be from the character before the cursor character up to and including 

39877 the first character in the line. 

39878 3. Any text copied to a buffer shall be in character mode. 

39879 If not used as a motion command: 

39880 Current line: Unchanged. 

39881 Current column: The last column in which any portion of the first character in the line is 

39882 displayed, or if the line is empty, unchanged. 

39883 Execute an ex Command 

39884 Synopsis: : 

39885 Execute one or more ex commands. 

39886 If any portion of the screen other than the last line of the screen was overwritten by any ex 

39887 command (except shell), vi shall display a message indicating that it is waiting for an input from 

39888 the user, and shall then read a character. This action may also be taken for other, unspecified 

39889 reasons. 

39890 If the next character entered is a ' :', another ex command shall be accepted and executed. Any 

39891 other character shall cause the screen to be refreshed and vi shall return to command mode. 

39892 Current line: As specified for the ex command. 

39893 Current column: As specified for the ex command. 
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Repeat Find 

Synopsis: [count] ; 

This command shall be equivalent to the last F, f, T, or t command, with the specified count, and I 
with the same search character used for the last F, f, T, or t command. If there was no previous F, I 
f, T, or t command, it shall be an error. I 

Shift Left 

Synopsis: [count] < motion 

If the motion command is the < command repeated: I 

1. If there are less than count -1 lines after the current line in the edit buffer, it shall be an I 

error. I 

2. The text region shall be from the current line, up to and including the next count -1 lines. I 

Shift any line in the text region specified by the count and motion command one shiftwidth (see I 
the ex shiftwidth option) toward the start of the line, as described by the ex < command. The I 
unshifted lines shall be copied to the unnamed buffer in line mode. I 

Current line: If the motion was from the current cursor position toward the end of the edit I 
buffer, unchanged. Otherwise, set to the first line in the edit buffer that is part of the text region I 
specified by the motion command. I 

Current column: Set to non-<blank>. I 

Shift Right 

Synopsis: [count] > motion 

If the motion command is the > command repeated: I 

1. If there are less than count -1 lines after the current line in the edit buffer, it shall be an I 

error. I 

2. The text region shall be from the current line, up to and including the next count -1 lines. I 

Shift any line with characters in the text region specified by the count and motion command one I 
shiftwidth (see the ex shiftwidth option) away from the start of the line, as described by the ex > I 
command. The unshifted lines shall be copied into the unnamed buffer in line mode. I 

Current line: If the motion was from the current cursor position toward the end of the edit I 
buffer, unchanged. Otherwise, set to the first line in the edit buffer that is part of the text region I 
specified by the motion command. I 

Current column: Set to non-<blank>. I 

Scan Backwards for Regular Expression 

Synopsis: ? 

Scan backwards; The ? command shall be equivalent to the / command (see Find Regular I 
Expression on page 1046) with the following exceptions: I 

1. The input prompt shall be a ' ?'. I 

2. Each search shall begin from the character before the first character of the last match (or, if I 

it is the first search, the character before the cursor character). I 
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3. The search direction shall be from the cursor toward the beginning of the edit buffer, and 
the wrapscan edit option shall affect whether the search wraps to the end of the edit buffer 
and continues. 

4. The remembered search direction shall be set to backward. 

Execute 

Synopsis: Qbuffer 

If the buffer is specified as @, the last buffer executed shall be used. If no previous buffer has been 
executed, it shall be an error. 

Behave as if the contents of the named buffer were entered as standard input. After each line of a 
line-mode buffer, and all but the last line of a character mode buffer, behave as if a <newline> 
character were entered as standard input. 

If an error occurs during this process, an error message shall be written, and no more characters 
resulting from the execution of this command shall be processed. 

If a count is specified, behave as if that count were entered as user input before the characters 
from the @ buffer were entered. 

Current line: As specified for the individual commands. 

Current column: As specified for the individual commands. 

Reverse Case 

Synopsis: [count] 

Reverse the case of the current character and the next count -1 characters, such that lowercase 
characters that have uppercase counterparts shall be changed to uppercase characters, and 
uppercase characters that have lowercase counterparts shall be changed to lowercase characters, 
as prescribed by the current locale. No other characters shall be affected by this command. 

If there are less than count -1 characters after the cursor in the edit buffer, count shall be adjusted 
to the number of characters after the cursor in the edit buffer minus 1. 

For the purposes of this command, the next character after the last character on the line shall be 
the next character in the edit buffer. 

Current line: Set to the line including the (count-l)th character after the cursor. 

Current column: Set to the last column in which any portion of the {count- l)th character after the 
cursor is displayed. 

Reindent 

Synopsis: 

[count] =[ motion ] 

If the lisp option is set, reindents the specified lines, as though they were typed in with lisp and 
autoindent set. 

Current line: Unchanged. 

Current column: Move to the first non-<blank> character of the line or the last character if the 
line is a blank line. 
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Append 

Synopsis: [count] a I 

Enter text input mode after the current cursor position. No characters already in the edit buffer I 
shall be affected by this command. A count shall cause the input text to be appended count -1 I 
more times to the end of the input. I 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi I 
on page 1064). I 

Append at End-of-Line I 

Synopsis: [count] A I 

This command shall be equivalent to the vi command: I 

$ [ count ] a I 

(see Append). I 

Move Backward to Preceding Word 

Synopsis: [count] b 

With the exception that words are used as the delimiter instead of bigwords, this command shall I 
be equivalent to the B command. I 

Move Backward to Preceding Bigword 

Synopsis: [count] B 

If the edit buffer is empty or the cursor is on the first character of the edit buffer, it shall be an I 
error. If less than count bigwords begin between the cursor and the start of the edit buffer, count I 
shall be adjusted to the number of bigword beginnings between the cursor and the start of the I 
edit buffer. I 

If used as a motion command: I 

1. The text region shall be from the first character of the countth previous bigword beginning I 

up to but not including the cursor character. I 

2. Any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

Current line: Set to the line containing the current column . I 

Current column: Set to the last column upon which any part of the first character of the count th I 
previous bigword is displayed. I 

Change 

Synopsis: [ buffer ] [count] c motion I 

If the motion command is the c command repeated: I 

1. The buffer text shall be in line mode. I 

2. If there are less than count -1 lines after the current line in the edit buffer, it shall be an I 

error. I 
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3. The text region shall be from the current line up to and including the next count -1 lines. 

Otherwise, the buffer text mode and text region shall be as specified by the motion command. 

The replaced text shall be copied into buffer, if specified, and into the unnamed buffer. If the text 
to be replaced contains characters from more than a single line, or the buffer text is in line mode, 
the replaced text shall be copied into the numeric buffers as well. 

If the buffer text is in line mode: 

1. Any lines that contain characters in the region shall be deleted, and the editor shall enter 
text input mode at the beginning of a new line which shall replace the first line deleted. 

2. If the autoindent edit option is set, autoindent characters equal to the autoindent 
characters on the first line deleted shall be inserted as if entered by the user. 

Otherwise, if characters from more than one line are in the region of text: 

1. The text shall be deleted. 

2. Any text remaining in the last line in the text region shall be appended to the first line in 
the region, and the last line in the region shall be deleted. 

3. The editor shall enter text input mode after the last character not deleted from the first line 
in the text region, if any; otherwise, on the first column of the first line in the region. 

Otherwise: 

1. If the glyph for ' $' is smaller than the region, the end of the region shall be marked with a 

' $'• 

2. The editor shall enter text input mode, overwriting the region of text. 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi 
on page 1064). 

Change to End-of-Line 

Synopsis: [ buffer ] [count] C 

This command shall be equivalent to the vi command: 

[buffer ][count] c$ 

See the c command. 

Delete 

Synopsis: [ buffer ] [count] d motion 

If the motion command is the d command repeated: 

1. The buffer text shall be in line mode. 

2. If there are less than count -1 lines after the current line in the edit buffer, it shall be an 
error. 

3. The text region shall be from the current line up to and including the next count -1 lines. 

Otherwise, the buffer text mode and text region shall be as specified by the motion command. 

If in open mode, and the current line is deleted, and the line remains on the display, an ' @' 
character shall be displayed as the first glyph of that line. 
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Delete the region of text into buffer, if specified, and into the unnamed buffer. If the text to be I 
deleted contains characters from more than a single line, or the buffer text is in line mode, the I 
deleted text shall be copied into the numeric buffers, as well. I 

Current line: Set to the first text region line that appears in the edit buffer, unless that line has I 
been deleted, in which case it shall be set to the last line in the edit buffer, or line 1 if the edit I 
buffer is empty. I 

Current column: I 

1. If the line is empty, set to column position 1. I 

2. Otherwise, if the buffer text is in line mode or the motion was from the cursor toward the I 

end of the edit buffer: I 

a. If a character from the current line is displayed in the current column, set to the last I 

column that displays any portion of that character. I 

b. Otherwise, set to the last column in which any portion of any character in the line is I 

displayed. I 

3. Otherwise, if a character is displayed in the column that began the text region, set to the I 

last column that displays any portion of that character. I 

4. Otherwise, set to the last column in which any portion of any character in the line is I 

displayed. I 

Delete to End-of-Line I 

Synopsis: [buffer ] D I 

Delete the text from the current position to the end of the current line; equivalent to the vi I 
command: I 

[buffer] d$ 


Move to End-of-Word I 

Synopsis: [count] e 

With the exception that words are used instead of bigwords as the delimiter, this command shall I 
be equivalent to the E command. I 

Move to End-of-Bigword 

Synopsis: [count] E 

If the edit buffer is empty it shall be an error. If less than count bigwords end between the cursor I 
and the end of the edit buffer, count shall be adjusted to the number of bigword endings between I 
the cursor and the end of the edit buffer. I 

If used as a motion command: I 

1. The text region shall be from the last character of the count th next bigword up to and I 

including the cursor character. I 

2. Any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

Current line: Set to the line containing the current column. I 
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Current column: Set to the last column upon which any part of the last character of the countth I 
next bigword is displayed. I 

Find Character in Current Line (Forward) 

Synopsis: [count] f character 

It shall be an error if count occurrences of the character do not occur after the cursor in the line. I 
If used as a motion command: I 

1. The text range shall be from the cursor character up to and including the countth I 

occurrence of the specified character after the cursor. I 

2. Any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

Current line: Unchanged. I 

Current column: Set to the last column in which any portion of the countth occurrence of the I 
specified character after the cursor appears in the line. I 

Find Character in Current Line (Reverse) 

Synopsis: [count] F character 

It shall be an error if count occurrences of the character do not occur before the cursor in the line. I 
If used as a motion command: I 

1. The text region shall be from the count th occurrence of the specified character before the I 

cursor, up to, but not including the cursor character. I 

2. Any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

Current line: Unchanged. I 

Current column: Set to the last column in which any portion of the countth occurrence of the I 
specified character before the cursor appears in the line. I 

Move to Line 

Synopsis: [count] G 

If count is not specified, it shall default to the last line of the edit buffer. If count is greater than I 

the last line of the edit buffer, it shall be an error. I 

If used as a motion command: I 

1. The text region shall be from the cursor line up to and including the specified line. I 

2. Any text copied to a buffer shall be in line mode. I 

If not used as a motion command: I 

Current line: Set to count if count if specified; otherwise, the last line. I 

Current column: Set to non-<blank>. I 
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Move to Top of Screen 

Synopsis: [count] H 

If the beginning of the line count greater than the first line of which any portion appears on the I 
display does not exist, it shall be an error. I 

If used as a motion command: I 

1. If in open mode, the text region shall be the current line. I 

2. Otherwise, the text region shall be from the starting line up to and including (the first line I 

of the display + count -1). I 

3. Any text copied to a buffer shall be in line mode. I 

If not used as a motion command: I 

If in open mode, this command shall set the current column to non-<blank> and do nothing else. I 
Otherwise, it shall set the current line and current column as follows. I 

Current line: Set to (the first line of the display + count -1). I 

Current column: Set to non-<blank>. I 

Insert Before Cursor 

Synopsis: [count] i 

Enter text input mode before the current cursor position. No characters already in the edit buffer I 
shall be affected by this command. A count shall cause the input text to be appended count -1 I 
more times to the end of the input. I 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi I 
on page 1064). I 

Insert at Beginning of Line 

Synopsis: [count] I 

This command shall be equivalent to the vi command '[count ]i command. I 

Join 

Synopsis: [count] J 

If the current line is the last line in the edit buffer, it shall be an error. I 

This command shall be equivalent to the ex join command with no addresses, and an ex I 
command count value of 1 if count was not specified or if a count of 1 was specified, and an ex I 
command count value of count -1 for any other value of count, except that the current line and I 
column shall be set as follows. I 

Current line: Unchanged. 

Current column: The last column in which any portion of the character following the last I 
character in the initial line is displayed, or the last character in the line if no characters were I 
appended. I 


Commands and Utilities, Issue 6 


1055 





VI 


Utilities 


40150 

40151 

40152 

40153 

40154 

40155 

40156 

40157 

40158 

40159 

40160 

40161 

40162 

40163 

40164 

40165 

40166 

40167 

40168 

40169 

40170 

40171 

40172 

40173 

40174 

40175 

40176 

40177 

40178 

40179 

40180 

40181 

40182 


Move to Bottom of Screen 

Synopsis: [count] L 

If the beginning of the line count less than the last line of which any portion appears on the I 
display does not exist, it shall be an error. I 

If used as a motion command: I 

1. If in open mode, the text region shall be the current line. I 

2. Otherwise, the text region shall include all lines from the starting cursor line to (the last I 

line of the display -{count -1)). I 

3. Any text copied to a buffer shall be in line mode. I 

If not used as a motion command: I 

1. If in open mode, this command shall set the current column to non-<blank> and do I 

nothing else. I 

2. Otherwise, it shall set the current line and current column as follows. I 

Current line: Set to (the last line of the display -{count -1)). I 

Current column: Set to non-<blank>. I 

Mark Position 

Synopsis: m letter 

This command shall be equivalent to the ex mark command with the specified character as an I 
argument. I 

Move to Middle of Screen 

Synopsis: M 

The middle line of the display shall be calculated as follows: I 

(the top line of the display) + (((number of lines displayed) +1) /2) —1 I 
If used as a motion command: I 

1. If in open mode, the text region shall be the current line. I 

2. Otherwise, the text region shall include all lines from the starting cursor line up to and I 

including the middle line of the display. I 

3. Any text copied to a buffer shall be in line mode. I 

If not used as a motion command: I 

If in open mode, this command shall set the current column to non-<blank> and do nothing else. I 
Otherwise, it shall set the current line and current column as follows. I 

Current line: Set to the middle line of the display. I 

Current column: Set to non-<blank>. I 
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Repeat Regular Expression Find (Forward) 

Synopsis: n 

If the remembered search direction was forward, the n command shall be equivalent to the vi / 
command with no characters entered by the user. Otherwise, it shall be equivalent to the vi ? 
command with no characters entered by the user. 

If the n command is used as a motion command for the ! command, the editor shall not enter 
text input mode on the last line on the screen, and shall behave as if the user entered a single ' !' 
character as the text input. 

Repeat Regular Expression Find (Reverse) 

Synopsis: N 

Scan for the next match of the last pattern given to / or ?, but in the reverse direction; this is the 
reverse of n. 

If the remembered search direction was forward, the N command shall be equivalent to the vi ? 
command with no characters entered by the user. Otherwise, it shall be equivalent to the vi / 
command with no characters entered by the user. If the N command is used as a motion 
command for the ! command, the editor shall not enter text input mode on the last line on the 
screen, and shall behave as if the user entered a single ! character as the text input. 

Insert Empty Fine Below 

Synopsis: o 

Enter text input mode in a new line appended after the current line. A couni shall cause the input 
text to be appended count -1 more times to the end of the already added text, each time starting 
on a new, appended line. 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi 
on page 1064). 

Insert Empty Fine Above 

Synopsis: O 

Enter text input mode in a new line inserted before the current line. A count shall cause the input 
text to be appended count -1 more times to the end of the already added text, each time starting 
on a new, appended line. 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi 
on page 1064). 

Put from Buffer Following 

Synopsis: [buffer] p 

If no buffer is specified, the unnamed buffer shall be used. 

If the buffer text is in line mode, the text shall be appended below the current line, and each line 
of the buffer shall become a new line in the edit buffer. A count shall cause the buffer text to be 
appended count -1 more times to the end of the already added text, each time starting on a new, 
appended line. 

If the buffer text is in character mode, the text shall be appended into the current line after the 
cursor, and each line of the buffer other than the first and last shall become a new line in the edit 
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buffer. A count shall cause the buffer text to be appended count -1 more times to the end of the 
already added text, each time starting after the last added character. 

Current line: If the buffer text is in line mode, set the line to line +1; otherwise, unchanged. 
Current column: If the buffer text is in line mode: 

1. If there is a non-<blank> character in the first line of the buffer, set to the last column on 
which any portion of the first non-<blank> character in the line is displayed. 

2. If there is no non-<blank> character in the first line of the buffer, set to the last column on 
which any portion of the last character in the first line of the buffer is displayed. 

If the buffer text is in character mode: 

1. If the text in the buffer is from more than a single line, then set to the last column on which 
any portion of the first character from the buffer is displayed. 

2. Otherwise, if the buffer is the unnamed buffer, set to the last column on which any portion 
of the last character from the buffer is displayed. 

3. Otherwise, set to the first column on which any portion of the first character from the 
buffer is displayed. 

Put from Buffer Before 

Synopsis: [buffer ] P 

If no buffer is specified, the unnamed buffer shall be used. 

If the buffer text is in line mode, the text shall be inserted above the current line, and each line of 
the buffer shall become a new line in the edit buffer. A count shall cause the buffer text to be 
appended count -1 more times to the end of the already added text, each time starting on a new, 
appended line. 

If the buffer text is in character mode, the text shall be inserted into the current line before the 
cursor, and each line of the buffer other than the first and last shall become a new line in the edit 
buffer. A count shall cause the buffer text to be appended count -1 more times to the end of the 
already added text, each time starting after the last added character. 

Current line: Unchanged. 

Current column: If the buffer text is in line mode: 

1. If there is a non-<blank> character in the first line of the buffer, set to the last column on 
which any portion of that character is displayed. 

2. If there is no non-<blank> character in the first line of the buffer, set to the last column on 
which any portion of the last character in the first line of the buffer is displayed. 

If the buffer text is in character mode: 

1. If the buffer is the unnamed buffer, set to the last column on which any portion of the last 
character from the buffer is displayed. 

2. Otherwise, set to the first column on which any portion of the first character from the 
buffer is displayed. 
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Enter ex Mode I 

Synopsis: Q 

Leave visual or open mode and enter ex command mode. I 

Current line: Unchanged. 

Current column: Unchanged. 

Replace Character 

Synopsis: [count] r character 

Replace the count characters at and after the cursor with the specified character. If there are less I 
than count characters at and after the cursor on the line, it shall be an error. I 

If character is <control>-V, any next character other than the <newline> shall be stripped of any I 
special meaning and used as a literal character. I 

If character is <ESC>, no replacement shall be made and the current line and current column I 
shall be unchanged. I 

If character is <carriage-return> or <newline>, count new lines shall be appended to the current I 
line. All but the last of these lines shall be empty, count characters at and after the cursor shall be I 
discarded, and any remaining characters after the cursor in the current line shall be moved to the I 
last of the new lines. If the autoindent edit option is set, they shall be preceded by the same I 
number of autoindent characters found on the line from which the command was executed. I 

Current line: Unchanged unless the replacement character is a <carriage-return> or <newline> I 
character, in which case it shall be set to line + count. I 

Current column: Set to the last column position on which a portion of the last replaced character I 
is displayed, or if the replacement character caused new lines to be created, set to non-<blank>. I 

Replace Characters 

Synopsis: R 

Enter text input mode at the current cursor position. A count shall cause the input text to be I 
appended count -1 more times to the end of the input. I 

Current line/column: As specified for the text input commands (see Input Mode Commands in vi I 
on page 1064). I 

Substitute Character 

Synopsis: [ buffer ] [count] s 

This command shall be equivalent to the vi command: I 

[buffer ][count] c<space> 
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Substitute Lines 

Synopsis: [buffer] [count] S 

This command shall be equivalent to the vi command: 

[buffer] [count] c_ 

Move Cursor to Before Character (Forward) 

Synopsis: [count] t character 

It shall be an error if count occurrences of the character do not occur after the cursor in the line. 

If used as a motion command: 

1. The text region shall be from the cursor up to but not including the count th occurrence of 
the specified character after the cursor. 

2. Any text copied to a buffer shall be in character mode. 

If not used as a motion command: 

Current line: Unchanged. 

Current column: Set to the last column in which any portion of the character before the countth 
occurrence of the specified character after the cursor appears in the line. 

Move Cursor to After Character (Reverse) 

Synopsis: [count] T character 

It shall be an error if count occurrences of the character do not occur before the cursor in the line. 
If used as a motion command: 

1. If the character before the cursor is the specified character, it shall be an error. 

2. The text region shall be from the character before the cursor up to but not including the 
count th occurrence of the specified character before the cursor. 

3. Any text copied to a buffer shall be in character mode. 

If not used as a motion command: 

Current line: Unchanged. 

Current column: Set to the last column in which any portion of the character after the countth 
occurrence of the specified character before the cursor appears in the line. 

Undo 

Synopsis: u 

This command shall be equivalent to the ex undo command except that the current line and 
current column shall be set as follows: 

Current line: Set to the first line added or changed if any; otherwise, move to the line preceding 
any deleted text if one exists; otherwise, move to line 1. 

Current column: If undoing an ex command, set to the first non-<blank> character. 

Otherwise, if undoing a text input command: 
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1. If the command was an C, c, O, o, R, S, or s command, the current column shall be set to I 

the value it held when the text input command was entered. I 

2. Otherwise, set to the last column in which any portion of the first character after the I 

deleted text is displayed, or, if no characters follow the text deleted from this line, set to the I 
last column in which any portion of the last character in the line is displayed, or 1 if the line I 
is empty. I 

Otherwise, if a single line was modified (that is, not added or deleted) by the u command: I 

1. If text was added or changed, set to the last column in which any portion of the first I 

character added or changed is displayed. I 

2. If text was deleted, set to the last column in which any portion of the first character after I 

the deleted text is displayed, or, if no characters follow the deleted text, set to the last I 
column in which any portion of the last character in the line is displayed, or 1 if the line is I 
empty. I 

Otherwise, set to non-<blank>. I 

Undo Current Line 

Synopsis: U 

Restore the current line to its state immediately before the most recent time that it became the I 
current line. I 

Current line: Unchanged. 

Current column: Set to the first column in the line in which any portion of the first character in I 
the line is displayed. I 

Move to Beginning of Word 

Synopsis: [count] w 

With the exception that words are used as the delimiter instead of bigwords, this command shall I 
be equivalent to the W command. I 

Move to Beginning of Bigword 

Synopsis: [count] W 

If the edit buffer is empty, it shall be an error. If there are less than count bigwords between the I 
cursor and the end of the edit buffer, count shall be adjusted to move the cursor to the last I 
bigword in the edit buffer. I 

If used as a motion command: I 

1. If the associated command is c, count is 1, and the cursor is on a <blank> character, the I 

region of text shall be the current character and no further action shall be taken. I 

2. If there are less than count bigwords between the cursor and the end of the edit buffer, then I 

the command shall succeed, and the region of text shall include the last character of the I 
edit buffer. I 

3. If there are <blank> characters or an end-of-line that precede the count th bigword, and the I 

associated command is c, the region of text shall be up to and including the last character I 
before the preceding <blank> characters or end-of-line. I 
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4. If there are <blank> characters or an end-of-line that precede the bigword, and the I 

associated command is d or y, the region of text shall be up to and including the last I 
<blank> character before the start of the bigword or end-of-line. I 

5. Any text copied to a buffer shall be in character mode. I 

If not used as a motion command: I 

1. If the cursor is on the last character of the edit buffer, it shall be an error. I 

Current line: Set to the line containing the current column. I 

Current column: Set to the last column in which any part of the first character of the count th next I 
bigword is displayed. I 

Delete Character at Cursor 

Synopsis: [ buffer] [count] x 

Delete the count characters at and after the current character into buffer, if specified, and into the I 
unnamed buffer. I 

If the line is empty, it shall be an error. If there are less than count characters at and after the I 
cursor on the current line, count shall be adjusted to the number of characters at and after the I 
cursor. I 

Current line: Unchanged. 

Current column: If the line is empty, set to column position 1. Otherwise, if there were count or I 
less characters at and after the cursor on the current line, set to the last column that displays any I 
part of the last character of the line. Otherwise, unchanged. I 

Delete Character Before Cursor 

Synopsis: [ buffer] [count] X 

Delete the count characters before the current character into buffer, if specified, and into the I 
unnamed buffer. I 

If there are no characters before the current character on the current line, it shall be an error. If I 
there are less than count previous characters on the current line, count shall be adjusted to the I 
number of previous characters on the line. I 

Current line: Unchanged. 

Current column: Set to ( current column - the width of the deleted characters). I 

Yank 

Synopsis: [buffer] [count] y motion 

Copy (yank) the region of text into buffer, if specified, and into the unnamed buffer. I 

If the motion command is the y command repeated: I 

1. The buffer shall be in line mode. I 

2. If there are less than count -1 lines after the current line in the edit buffer, it shall be an I 

error. I 

3. The text region shall be from the current line up to and including the next count -1 lines. I 
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Otherwise, the buffer text mode and text region shall be as specified by the motion command. 

Current line: If the motion was from the current cursor position toward the end of the edit 
buffer, unchanged. Otherwise, set to the first line in the edit buffer that is part of the text region 
specified by the motion command. 

Current column: 

1. If the motion was from the current cursor position toward the end of the edit buffer, 
unchanged. 

2. Otherwise, if the current line is empty, set to column position 1. 

3. Otherwise, set to the last column that displays any part of the first character in the file that 
is part of the text region specified by the motion command. 

Yank Current Line 

Synopsis: [ buffer] [count] Y 

This command shall be equivalent to the vi command: 

[ buffer][count] y_ 


Redraw Window 

If in open mode, the z command shall have the Synopsis: 

Synopsis: [count] z 

If count is not specified, it shall default to the window edit option -1. The z command shall be 
equivalent to the ex z command, with a type character of = and a count of count -2, except that 
the current line and current column shall be set as follows, and the window edit option shall not 
be affected. If the calculation for the count argument would result in a negative number, the 
count argument to the ex z command shall be zero. A blank line shall be written after the last line 
is written. 

Current line: Unchanged. 

Current column: Unchanged. 

If not in open mode, the z command shall have the following Synopsis: 

Synopsis: [line] z [count] character 

If line is not specified, it shall default to the current line. If line is specified, but is greater than the 
number of lines in the edit buffer, it shall default to the number of lines in the edit buffer. 

If count is specified, the value of the window edit option shall be set to count (as described in the 
ex window command), and the screen shall be redrawn. 

line shall be placed as specified by the following characters: 

<newline>, <carriage-return> 

Place the beginning of the line on the first line of the display. 

Place the beginning of the line in the center of the display. The middle line of the display 
shall be calculated as described for the M command. 

- Place an unspecified portion of the line on the last line of the display. 

+ If line was specified, equivalent to the <newline> case. If line was not specified, display a 
screen where the first line of the display shall be (current last line) +1. If there are no lines 
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after the last line in the display, it shall be an error. 

A If line was specified, display a screen where the last line of the display shall contain an 
unspecified portion of the first line of a display that had an unspecified portion of the 
specified line on the last line of the display. If this calculation results in a line before the 
beginning of the edit buffer, display the first screen of the edit buffer. 

Otherwise, display a screen where the last line of the display shall contain an unspecified 
portion of (current first line -1). If this calculation results in a line before the beginning of 
the edit buffer, it shall be an error. 

Current line: If line and the ' '' character were specified: 

1. If the first screen was displayed as a result of the command attempting to display lines 
before the beginning of the edit buffer: if the first screen was already displayed, 
unchanged; otherwise, set to (current first line -1). 

2. Otherwise, set to the last line of the display. 

If line and the ' +' character were specified, set to the first line of the display. 

Otherwise, if line was specified, set to line. 

Otherwise, unchanged. 

Current column: Set to non-<blank>. 

Exit 

Synopsis: ZZ 

This command shall be equivalent to the ex xit command with no addresses, trailing !, or file 
name (see the ex xit command). 

Input Mode Commands in vi 

In text input mode, the current line shall consist of zero or more of the following categories: 

1. Characters preceding the text input entry point 

Characters in this category shall not be modified during text input mode. 

2. autoindent characters 

autoindent characters shall be automatically inserted into each line that is created in text 
input mode, either as a result of entering a <newline> character or <carriage-return> 
character while in text input mode, or as an effect of the command itself; for example, O or 
o (see the ex autoindent command), as if entered by the user. 

It shall be possible to erase autoindent characters with the <control>-D command; it is 
unspecified whether they can be erased by <control>-H, <control>-U, and <control>-W 
characters. Erasing any autoindent character turns the glyph into erase-columns and 
deletes the character from the edit buffer, but does not change its representation on the 
screen. 

3. Text input characters 

Text input characters are the characters entered by the user. Erasing any text input 
character turns the glyph into erase-columns and deletes the character from the edit buffer, 
but does not change its representation on the screen. 
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Each text input character entered by the user (that does not have a special meaning) shall 
be treated as follows: 

a. The text input character shall be appended to the last character in the edit buffer 
from the first, second, or third categories. 

b. If there are no erase-columns on the screen, the text input command was the R 
command, and characters in the fifth category from the original line follow the 
cursor, the next such character shall be deleted from the edit buffer. If the slowopen 
edit option is not set, the corresponding glyph on the screen shall become erase- 
columns. 

c. If there are erase-columns on the screen, as many columns as they occupy, or as are 
necessary, shall be overwritten to display the text input character. (If only part of a 
multi-column glyph is overwritten, the remainder shall be left on the screen, and 
continue to be treated as erase-columns; it is unspecified whether the remainder of 
the glyph is modified in any way.) 

d. If additional screen columns are needed to display the text input character: 

1. If the slowopen edit option is set, the text input characters shall be displayed 
on subsequent screen columns, overwriting any characters displayed in those 
columns. 

2. Otherwise, any characters currently displayed on or after the column on the 
screen where the text input character is to be displayed shall be pushed ahead 
the number of screen columns necessary to display the rest of the text input 
character. 

4. Erase-columns 

Erase-columns are not logically part of the edit buffer, appearing only on the screen, and 
may be overwritten on the screen by subsequent text input characters. When text input 
mode ends, all erase-columns shall no longer appear on the screen. 

Erase-columns are initially the region of text specified by the c command ( see Change on 
page 1051) however, erasing autoindent or text input characters causes the glyphs of the 
erased characters to be treated as erase-columns. 

5. Characters following the text region for the c command, or the text input entry point for all 
other commands 

Characters in this category shall not be modified during text input mode, except as 
specified in category 3.b. for the R text input command, or as <blank> characters deleted 
when a <newline> character or <carriage-return> character is entered. 

It is unspecified whether it is an error to attempt to erase past the beginning of a line that was 
created by the entry of a <newline> or <carriage-return> character during text input mode. If it 
is not an error, the editor shall behave as if the erasing character was entered immediately after 
the last text input character entered on the previous line, and all of the characters on the current 
line shall be treated as erase-columns. 

When text input mode is entered, or after a text input mode character is entered (except as 
specified for the special characters below), the cursor shall be positioned as follows: 

1. On the first column that displays any part of the first erase-column, if one exists 

2. Otherwise, if the slowopen edit option is set, on the first screen column after the last 
character in the first, second, or third categories, if one exists 
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3. Otherwise, the first column that displays any part of the first character in the fifth category, 
if one exists 

4. Otherwise, the screen column after the last character in the first, second, or third 
categories, if one exists 

5. Otherwise, on column position 1 

The characters that are updated on the screen during text input mode are unspecified, other than 
that the last text input character shall always be updated, and, if the slowopen edit option is not 
set, the current cursor character shall always be updated. 

The following specifications are for command characters entered during text input mode. 

NUL 

Synopsis: NUL 

If the first character of the text input is a NUL, the most recently input text shall be input as if 
entered by the user, and then text input mode shall be exited. The text shall be input literally; 
that is, characters are neither macro or abbreviation expanded, nor are any characters interpreted 
in any special manner. It is unspecified whether implementations shall support more than 256 
bytes of remembered input text. 

<control>-D 

Synopsis: <control>-D 

The <control>-D character shall have no special meaning when in text input mode for a line- 
oriented command (see Command Descriptions in vi on page 1031). 

This command need not be supported on block-mode terminals. 

If the cursor does not follow an autoindent character, or an autoindent character and a ' 0' or 
' '' character: 

1. If the cursor is in column position 1, the <control>-D character shall be discarded and no 
further action taken. 

2. Otherwise, the <control>-D character shall have no special meaning. 

If the last input character was a ' 0', the cursor shall be moved to column position 1. 

Otherwise, if the last input character was a ' *', the cursor shall be moved to column position 1. 
In addition, the autoindent level for the next input line shall be derived from the same line from 
which the autoindent level for the current input line was derived. 

Otherwise, the cursor shall be moved back to the column after the previous shiftwidth (see the 
ex shiftwidth command) boundary. 

All of the glyphs on columns between the starting cursor position and (inclusively) the ending 
cursor position shall become erase-columns as described in Input Mode Commands in vi on 
page 1064. 

Current line: Unchanged. 

Current column: Set to 1 if the <control>-D was preceded by a ' '' or 'O'; otherwise, set to 
(column -1) -((column -2) % shiftwidth). 
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<control>-H 

Synopsis: <control>-H 

If in text input mode for a line-oriented command, and there are no characters to erase, text 
input mode shall be terminated, no further action shall be done for this command, and the 
current line and column shall be unchanged. 

If there are characters other than autoindent characters that have been input on the current line 
before the cursor, the cursor shall move back one character. 

Otherwise, if there are autoindent characters on the current line before the cursor, it is 
implementation-dependent whether the <control>-H command is an error or if the cursor 
moves back one autoindent character. 

Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, 
it is implementation-dependent whether the <control>-H command is an error or if it is 
equivalent to entering <control>-H after the last input character on the previous input line. 

Otherwise, it shall be an error. 

All of the glyphs on columns between the starting cursor position and (inclusively) the ending 
cursor position shall become erase-columns as described in Input Mode Commands in vi on 
page 1064. 

The current erase character (see stty) shall cause an equivalent action to the <control>-H 
command, unless the previously inserted character was a backslash, in which case it shall be as 
if the literal current erase character had been inserted instead of the backslash. 

Current line: Unchanged, unless previously input lines are erased, in which case it shall be set to 
line-1. 

Current column: Set to the first column that displays any portion of the character backed up 
over. 

<newline> 

Synopsis: <newline> 

<carriage-return> 

<control>-J 
<control>-M 

If input was part of a line-oriented command, text input mode shall be terminated and the 
command shall continue execution with the input provided. 

Otherwise, terminate the current line. If there are no characters other than autoindent characters 
on the line, all characters on the line shall be discarded. Otherwise, it is unspecified whether the 
autoindent characters in the line are modified by entering these characters. 

Continue text input mode on a new line appended after the current line. If the slowopen edit 
option is set, the lines on the screen below the current line shall not be pushed down, but the 
first of them shall be cleared and shall appear to be overwritten. Otherwise, the lines of the 
screen below the current line shall be pushed down. 

If the autoindent edit option is set, an appropriate number of autoindent characters shall be 
added as a prefix to the line as described by the ex autoindent edit option. 

All columns after the cursor that are erase-columns (as described in Input Mode Commands in 
vi on page 1064) shall be discarded. 
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If the autoindent edit option is set, all <blank> characters immediately following the cursor shall 
be discarded. 

All remaining characters after the cursor shall be transferred to the new line, positioned after any 
autoindent characters. 

Current line : Set to current line +1. 

Current column: Set to the first column that displays any portion of the first character after the 
autoindent characters on the new line, if any, or the first column position after the last 
autoindent character, if any, or column position 1. 

<control>-T 

Synopsis: <control>-T 

The <control>-T character shall have no special meaning when in text input mode for a line- 
oriented command (see Command Descriptions in vi on page 1031). 

This command need not be supported on block-mode terminals. 

Behave as if the user entered the minimum number of «blank» characters necessary to move 
the cursor forward to the column position after the next shiftwidth (see the ex shiftwidth 
command) boundary. 

Current line: Unchanged. 

Current column: Set to column + shiftwidth - ((column -1) % shiftwidth). 

<control>-U 

Synopsis: <control>-U 

If there are characters other than autoindent characters that have been input on the current line 
before the cursor, the cursor shall move to the first character input after the autoindent 
characters. 

Otherwise, if there are autoindent characters on the current line before the cursor, it is 
implementation-dependent whether the <control>-U command is an error or if the cursor moves 
to the first column position on the line. 

Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, 
it is implementation-dependent whether the <control>-U command is an error or if it is 
equivalent to entering <control>-U after the last input character on the previous input line. 

Otherwise, it shall be an error. 

All of the glyphs on columns between the starting cursor position and (inclusively) the ending 
cursor position shall become erase-columns as described in Input Mode Commands in vi on 
page 1064. 

The current kill character (see stty) shall cause an equivalent action to the <control>-U 
command, unless the previously inserted character was a backslash, in which case it shall be as 
if the literal current kill character had been inserted instead of the backslash. 

Current line: Unchanged, unless previously input lines are erased, in which case it shall be set to 
line-1. 

Current column: Set to the first column that displays any portion of the last character backed up 
over. 
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<control>-V I 

Synopsis: <control>-V 

<control>-Q 

Allow the entry of any subsequent character, other than <control>-J or the character, as a literal 
character, removing any special meaning that it may have to the editor in text input mode. If a 
<control>-V or <control>-Q is entered before a <control>-J or <newline> character, the 
<control>-V or <control>-Q character shall be discarded, and the <control>-J or <newline> shall 
behave as described in the <newline> command character during input mode. 

For purposes of the display only, the editor shall behave as if a ' ~' character was entered, and 
the cursor shall be positioned as if overwriting the ' '' character. When a subsequent character 
is entered, the editor shall behave as if that character was entered instead of the original 
<control>-V or <control>-Q character. 

Current line: Unchanged. 

Current column: Unchanged. 

<control>-W 

Synopsis: <control>-W 

If there are characters other than autoindent characters that have been input on the current line 
before the cursor, the cursor shall move back over the last word preceding the cursor (including 
any <blank> characters between the end of the last word and the current cursor); the cursor shall 
not move to before the first character after the end of any autoindent characters. 

Otherwise, if there are autoindent characters on the current line before the cursor, it is 
implementation-dependent whether the <control>-W command is an error or if the cursor 
moves to the first column position on the line. 

Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, 
it is implementation-dependent whether the <control>-W command is an error or if it is 
equivalent to entering <control>-W after the last input character on the previous input line. 

Otherwise, it shall be an error. 

All of the glyphs on columns between the starting cursor position and (inclusively) the ending 
cursor position shall become erase-columns as described in Input Mode Commands in vi on 
page 1064. 

Current line: Unchanged, unless previously input lines are erased, in which case it shall be set to 
line-1. 

Current column: Set to the first column that displays any portion of the last character backed up 
over. 

<ESC> 

Synopsis: <ESC> 

If input was part of a line-oriented command: 

1. If interrupt was entered, text input mode shall be terminated and the editor shall return to 
command mode. The terminal shall be alerted. 

2. If <ESC> was entered, text input mode shall be terminated and the command shall 
continue execution with the input provided. 
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40686 Otherwise, terminate text input mode and return to command mode. 

40687 Any autoindent characters entered on newly created lines that have no other characters shall be 

40688 deleted. 

40689 Any leading autoindent and «blank» characters on newly created lines shall be rewritten to 

40690 be the minimum number of «blank» characters possible. 

40691 The screen shall be redisplayed as necessary to match the contents of the edit buffer. 

40692 Current line: Unchanged. 

40693 Current column: 

40694 1. If there are text input characters on the current line, the column shall be set to the last 

40695 column where any portion of the last text input character is displayed. 

40696 2. Otherwise, if a character is displayed in the current column, unchanged. 

40697 3. Otherwise, set to column position 1. 

40698 EXIT STATUS 

40699 The following exit values shall be returned: 

40700 0 Successful completion. 

40701 >0 An error occurred. 

40702 CONSEQUENCES OF ERRORS 

40703 When any error is encountered and the standard input is not a terminal device file, vi shall not 

40704 write the file or return to command or text input mode, and shall terminate with a non-zero exit 

40705 status. 

40706 Otherwise, when an unrecoverable error is encountered it shall be equivalent to a SIGHUP 

40707 asynchronous event. 

40708 Otherwise, when an error is encountered, the editor shall behave as specified in Command 

40709 Descriptions in vi on page 1031. 

40710 APPLICATION USAGE 

40711 Application writers should note that this utility need not be provided on systems that do not 

40712 support the User Portability Utilities option. 

40713 EXAMPLES 

40714 None. 

40715 RATIONALE 

40716 See the RATIONALE for ex for more information on vi. Major portions of the vi utility 

40717 specification point to ex to avoid inadvertent divergence. While ex and vi have historically been 

40718 implemented as a single utility, this is not required by IEEE Std. 1003.1-200x. 

40719 It is recognized that portions of vi would be difficult, if not impossible, to implement 

40720 satisfactorily on a block-mode terminal, or a terminal without any form of cursor addressing, 

40721 thus it is not a mandatory requirement that such features should work on all terminals. It is the 

40722 intention, however, that a vi implementation should provide the full set of capabilities on all 

40723 terminals capable of supporting them. 

40724 Historically, vi exited immediately if the standard input was not a terminal. 

40725 IEEE Std. 1003.1-200x permits, but does not require, this behavior. An end-of-file condition is not 

40726 equivalent to an end-of-file character. A common end-of-file character, <control>-D, is 

40727 historically a vi command. 
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The text in the STANDARD OUTPUT section reflects the usage of the verb display in this section; 
some implementations of vi use standard output to write to the terminal, but 
IEEE Std. 1003.1-200x does not require that to be the case. 

Historically, implementations reverted to open mode if the terminal was incapable of 
supporting full visual mode. IEEE Std. 1003.1-200x requires this behavior. Historically, the open 
mode of vi behaved roughly equivalently to the visual mode, with the exception that only a 
single physical line from the edit buffer was kept current at any time. This line was normally 
displayed on the next-to-last line of a terminal with cursor addressing (and the last line 
performed its normal visual functions for line-oriented commands and messages). In addition, 
some few commands behaved differently in open mode than in visual mode. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, ex and vi implementations have expected text to proceed in the usual 
European/Latin order of left to right, top to bottom. There is no requirement in 
IEEE Std. 1003.1-200x that this be the case. The specification was deliberately written using 
words like "before", "after", "first", and "last" in order to permit implementations to support 
the natural text order of the language. 

Historically, lines past the end of the edit buffer were marked with single tilde (' ~') characters; 
that is, if the one-based display was 20 lines in length, and the last line of the file was on line one, 
then lines 2-20 would contain only a single ' ~' character. 

Historically, the vi editor attempted to display only complete lines at the bottom of the screen (it 
did display partial lines at the top of the screen). If a line was too long to fit in its entirety at the 
bottom of the screen, the screen lines where the line would have been displayed were displayed 
as single ' @' characters, instead of displaying part of the line. IEEE Std. 1003.1-200x permits, but 
does not require, this behavior. Implementations are encouraged to attempt always to display a 
complete line at the bottom of the screen when doing scrolling or screen positioning by physical 
lines. 

Historically, lines marked with ' @' were also used to minimize output to dumb terminals over 
slow lines; that is, changes local to the cursor were updated, but changes to lines on the screen 
that were not close to the cursor were simply marked with an ' @' sign instead of being updated 
to match the current text. IEEE Std. 1003.1-200x permits, but does not require this feature 
because it is used ever less frequently as terminals become smarter and connections are faster. 

Initialization in ex and vi 

Historically, vi always had a line in the edit buffer, even if the edit buffer was "empty". For 
example: 

1. The ex command = executed from visual mode wrote "1" when the buffer was empty. 

2. Writes from visual mode of an empty edit buffer wrote files of a single character (a 
<newline> character), while writes from ex mode of an empty edit buffer wrote empty 
files. 

3. Put and read commands into an empty edit buffer left an empty line at the top of the edit 
buffer. 

For consistency, IEEE Std. 1003.1-200x does not permit any of these behaviors. 

Historically, vi did not always return the terminal to its original modes; for example, ICRNL was 
modified if it was not originally set. IEEE Std. 1003.1-200x does not permit this behavior. 


Commands and Utilities, Issue 6 


1071 




40771 

40772 

40773 

40774 

40775 

40776 

40777 

40778 

40779 

40780 

40781 

40782 

40783 

40784 

40785 

40786 

40787 

40788 

40789 

40790 

40791 

40792 

40793 

40794 

40795 

40796 

40797 

40798 

40799 

40800 

40801 

40802 

40803 

40804 

40805 

40806 

40807 

40808 

40809 

40810 

40811 

40812 

40813 

40814 

40815 

40816 

40817 

40818 

40819 


vi Utilities 


Command Descriptions in vi 

Motion commands are among the most complicated aspects of vi to describe. With some 
exceptions, the text region and buffer type effect of a motion command on a vi command are 
described on a case-by-case basis. The descriptions of text regions in IEEE Std. 1003.1-200x are 
not intended to imply direction; that is, an inclusive region from line n to line n +5 is identical to 
a region from line n +5 to line n. This is of more than academic interest—movements to marks 
can be in either direction, and, if the wrapscan option is set, so can movements to search points. 
Historically, lines are always stored into buffers in text order; that is, from the start of the edit 
buffer to the end. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, command counts were applied to any associated motion, and were multiplicative 
to any supplied motion count. For example, 2cw is the same as c2w, and 2c3w is the same as 
c6w. IEEE Std. 1003.1-200x requires this behavior. Historically, vi commands that used 
bigwords, words, paragraphs, and sentences as objects treated groups of empty lines, or lines 
that contained only <blank> characters, inconsistently. Some commands treated them as a single 
entity, while others treated each line separately. For example, the w, W, and B commands treated 
groups of empty lines as individual words; that is, the command would move the cursor to each 
new empty line. The e and E commands treated groups of empty lines as a single word; that is, 
the first use would move past the group of lines. The b command would just beep at the user, or 
if done from the start of the line as a motion command, fail in unexpected ways. If the lines 
contained only (or ended with) <blank> characters, the w and W commands would just beep at 
the user, the E and e commands would treat the group as a single word, and the B and b 
commands would treat the lines as individual words. For consistency and simplicity of 
specification, IEEE Std. 1003.1-200x requires that all vi commands treat groups of empty or 
<blank> character-filled lines as a single entity, and that movement through lines ending with 
<blank> characters be consistent with other movements. 

Historically, vi documentation indicated that any number of double quotes were skipped after 
punctuation marks at sentence boundaries; however, implementations only skipped single 
quotes. IEEE Std. 1003.1-200x requires both to be skipped. 

Historically, the first and last characters in the edit buffer were word boundaries. This historical 
practice is required by IEEE Std. 1003.1-200x. 

Historically, vi attempted to update the minimum number of columns on the screen possible, 
which could lead to misleading information being displayed. IEEE Std. 1003.1-200x makes no 
requirements other than that the current character being entered is displayed correctly, leaving 
all other decisions in this area up to the implementation. 

Historically, lines were arbitrarily folded between columns of any characters that required 
multiple column positions on the screen, with the exception of tabs, which terminated at the 
right-hand margin. IEEE Std. 1003.1-200x permits the former and requires the latter. 
Implementations that do not arbitrarily break lines between columns of characters that occupy 
multiple column positions should not permit the cursor to rest on a column that does not 
contain any part of a character. 

The historical vi had a problem in that all movements were by physical lines, not by logical, or 
screen, lines. This is often the right thing to do; for example, single line movements, such as j or 
k, should work on physical lines. Commands like dj, or j., where . is a change command, only 
make sense for physical lines. It is not, however, the right thing to do for screen motion or 
scrolling commands like <control>-D, <control>-F, and H. If the window is fairly small, using 
physical lines in these cases can result in completely random motion; for example, l<control>-D 
can result in a completely changed screen, without any overlap. This is clearly not what the user 
wanted. The problem is even worse in the case of the H, L, and M commands—as they position 
the cursor at the first non-<blank> character of the line, they may all refer to the same location in 
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large lines, and will result in no movement at all. 

In addition, if the line is larger than the screen, using physical lines can make it impossible to 
display parts of the line—there are not any commands that do not display the beginning of the 
line in historical vi, and if both the beginning and end of the line cannot be on the screen at the 
same time, the user suffers. Finally, the page and half-page scrolling commands historically 
moved to the first non-<blank> character in the new line. If the line is approximately the same 
size as the screen, this is inadequate because the cursor before and after a <control>-D command 
will refer to the same location on the screen. 

Implementations of ex and vi exist that do not have these problems because the relevant 
commands (<control>-B, <control>-D, <control>-F, <control>-U, <control>-Y, <control>-E, H, L, 
and M) operate on logical screen lines, not physical edit buffer lines. 

IEEE Std. 1003.1-200x does not permit this behavior by default because the standard developers 
believed that users would find it too confusing. However, historical practice has been relaxed. 
For example, ex and vi historically attempted, albeit sometimes unsuccessfully, to never put part 
of a line on the last lines of a screen; for example, if a line would not fit in its entirety, no part of 
the line was displayed, and the screen lines corresponding to the line contained single ' @' 
characters. This behavior is permitted, but not required by IEEE Std. 1003.1-200x, so that it is 
possible for implementations to support long lines in small screens more reasonably without 
changing the commands to be logically (instead of physically) oriented. IEEE Std. 1003.1-200x 
also permits implementations to refuse to edit any edit buffer containing a line that will not fit 
on the screen in its entirety. 

The display area (for example, the value of the window edit option) has historically been 
"grown”, or expanded, to display new text when local movements are done in displays where 
the number of lines displayed is less than the maximum possible. Expansion has historically 
been the first choice, when the target line is less than the maximum possible expansion value 
away. Scrolling has historically been the next choice, done when the target line is less than half a 
display away, and otherwise, the screen was redrawn. There were exceptions, however, in that 
ex commands generally always caused the screen to be redrawn. IEEE Std. 1003.1-200x does not 
specify a standard behavior because there may be external issues, such as connection speed, the 
number of characters necessary to redraw as opposed to scroll, or terminal capabilities that 
implementations will have to accommodate. 

The current line in IEEE Std. 1003.1-200x maps one-to-one to a physical line in the file. The 
current column does not. There are two different column values that are described by 
IEEE Std. 1003.1-200x. The first is the current column value as set by many of the vi commands. 
This value is remembered for the lifetime of the editor. The second column value is the actual 
position on the screen where the cursor rests. The two are not always the same. For example, 
when the cursor is backed by a multi-column character, the actual cursor position on the screen 
has historically been the last column of the character in command mode, and the first column of 
the character in input mode. 

Commands that set the current line, but that do not set the current cursor value (for example, j 
and k) attempt to get as close as possible to the remembered column position, so that the cursor 
tends to restrict itself to a vertical column as the user moves around in the edit buffer. 
IEEE Std. 1003.1-200x requires conformance to historical practice, requiring that the physical 
location of the cursor on the screen be adjusted from the current column value as necessary to 
support this historical behavior. 

Historically, only a single line (and for some terminals, a single line minus 1 column) of 
characters could be entered by the user for the line oriented commands; that is, :, !, /, or ?. 
IEEE Std. 1003.1-200x permits, but does not require, this limitation. 


Commands and Utilities, Issue 6 


1073 




VI 


Utilities 


40868 

40869 

40870 

40871 

40872 

40873 

40874 

40875 

40876 

40877 

40878 

40879 

40880 

40881 

40882 

40883 

40884 

40885 

40886 

40887 

40888 

40889 

40890 

40891 

40892 

40893 

40894 

40895 

40896 

40897 

40898 

40899 

40900 

40901 

40902 

40903 

40904 

40905 

40906 


Historically, "soft” errors in vi caused the terminal to be alerted, but no error message was 
displayed. As a general rule, no error message was displayed for errors in command execution 
in vi, when the error resulted from the user attempting an invalid or impossible action, or when 
a searched-for object was not found. Examples of soft errors included h at the left margin, 
<control>-B or [[ at the beginning of the file, 2G at the end of the file, and so on. In addition, 
errors such as %, ]],},), N, n, f, F, t, and T failing to find the searched-for object were soft as well. 
Less consistently, / and ? displayed an error message if the pattern was not found, /, ?, N, and n 
displayed an error message if no previous regular expression had been specified, and ; did not 
display an error message if no previous f, F, t, or T command had occurred. Also, behavior in 
this area might reasonably be based on a runtime evaluation of the speed of a network 
connection. Finally, some implementations have provided error messages for soft errors in 
order to assist naive users, based on the value of a verbose edit option. IEEE Std. 1003.1-200x 
does not list specific errors for which an error message shall be displayed. Implementations 
should conform to historical practice in the absence of any strong reason to diverge. 

Page Backwards 

The <control>-B and <control>-F commands historically considered it an error to attempt to 
page past the beginning or end of the file, whereas the <control>-D and <control>-U commands 
simply moved to the beginning or end of the file. For consistency, IEEE Std. 1003.1-200x requires 
the latter behavior for all four commands. All four commands still consider it an error if the 
current line is at the beginning (<control>-B, <control>-U) or end (<control>-F, <control>-D) of 
the file. Historically, the <control>-B and <control>-F commands skip two lines in order to 
include overlapping lines when a single command is entered. This makes less sense in the 
presence of a count, as there will be, by definition, no overlapping lines. The actual calculation 
used by historical implementations of the vi editor for <control>-B was: 

((current first line) — count W (window edit option)) +2 

and for <control>-F was: 

((current first line) + count W (window edit option)) —2 

This calculation does not work well when intermixing commands with and without counts; for 
example, 3<control>-F is not equivalent to entering the <control>-F command three times, and is 
not reversible by entering the <control>-B command three times. For consistency with other vi 
commands that take counts, IEEE Std. 1003.1-200x requires a different calculation. 

Scroll Forward 

The 4BSD and System V implementations of vi differed on the initial value used by the scroll 
command. 4BSD used: 

((window edit option) +1) /2 

while System V used the value of the scroll edit option. The System V version is specified by 
IEEE Std. 1003.1-200x because the standard developers believed that it was more intuitive and 
permitted the user a method of setting the scroll value initially without also setting the number 
of lines that are displayed. 
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Scroll Forward by Line 

Historically, the <control>-E and <control>-Y commands considered it an error if the last and 
first lines, respectively, were already on the screen. IEEE Std. 1003.1-200x requires conformance 
to historical practice. Historically, the <control>-E and <control>-Y commands had no effect in 
open mode. For simplicity and consistency of specification, IEEE Std. 1003.1-200x requires that 
they behave as usual, albeit with a single line screen. 

Clear and Redisplay 

The historical <control>-L command refreshed the screen exactly as it was supposed to be 
currently displayed, replacing any ' @' characters for lines that had been deleted but not 
updated on the screen with refreshed ' @' characters. The intent of the <control>-L command is 
to refresh when the screen has been accidentally overwritten; for example, by a write command 
from another user, or modem noise. 

Redraw Screen 

The historical <control>-R command redisplayed only when necessary to update lines that had 
been deleted but not updated on the screen and that were flagged with ' @' characters. There is 
no requirement that the screen be in any way refreshed if no lines of this form are currently 
displayed. IEEE Std. 1003.1-200x permits implementations to extend this command to refresh 
lines on the screen flagged with ' @' characters because they are too long to be displayed in the 
current framework; however, the current line and column need not be modified. 

Search for tagstring 

Historically, the first non-<blank> character at or after the cursor was the first character, and all 
subsequent characters that were word characters, up to the end of the line, were included. For 
example, with the cursor on the leading space or on the ' #' character in the text "#bar@ ", the 
tag was "#bar". On the character 'b' it was "bar", and on the 'a', it was "ar". 
IEEE Std. 1003.1-200x requires this behavior. 

Replace Text with Results from Shell Command 

Historically, the <, >, and ! commands considered most cursor motions other than line-oriented 
motions an error; for example, the command >/foo<CR> succeeded, while the command >1 
failed, even though the text region described by the two commands might be identical. For 
consistency, all three commands only consider entire lines and not partial lines, and the region is 
defined as any line that contains a character that was specified by the motion. 

Move to Matching Character 

Other matching characters have been left implementation-dependent in order to allow 
extensions such as matching ' <' and ' >' for searching HTML, or #ifdef, #else, and #endif for 
searching C source. 
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Repeat Substitution 

IEEE Std. 1003.1-200x requires that any c and g flags specified to the previous substitute 
command be ignored; however, the r flag may still apply, if supported by the implementation. 

Return to Previous (Context or Section) 

The [[, ]], (,), {, and } commands are all affected by "section boundaries", but in some historical 
implementations not all of the commands recognize the same section boundaries. This is a bug, 
not a feature, and a unique section-boundary algorithm was not described for each command. 
One special case that is preserved is that the sentence command moves to the end of the last line 
of the edit buffer while the other commands go to the beginning, in order to preserve the 
traditional character cut semantics of the sentence command. Historically, vi section boundaries 
at the beginning and end of the edit buffer were the first non-<blank> character on the first and 
last lines of the edit buffer if one exists; otherwise, the last character of the first and last lines of 
the edit buffer if one exists. To increase consistency with other section locations, this has been 
simplified by IEEE Std. 1003.1-200x to the first character of the first and last lines of the edit 
buffer, or the first and the last lines of the edit buffer if they are empty. 

Sentence boundaries were problematic in the historical vi. They were not only the boundaries as 
defined for the section and paragraph commands, but they were the first non-<blank> character 
that occurred after those boundaries, as well. Historically, the vi section commands were 
documented as taking an optional window size as a count preceding the command. This was not 
implemented in historical versions, so IEEE Std. 1003.1-200x requires that the count repeat the 
command, for consistency with other vi commands. 

Repeat 

Historically, mapped commands other than text input commands could not be repeated using 
the period command. IEEE Std. 1003.1-200x requires conformance to historical practice. 

The restrictions on the interpretation of special characters (for example, <control>-H) in the 
repetition of text input mode commands is intended to match historical practice. For example, 
given the input sequence: 

iab<control>-H<control>-H<control>-Hdef<escape> 

the user should be informed of an error when the sequence is first entered, but not during a 
command repetition. The character <control>-T is specifically exempted from this restriction. 
Historical implementations of vi ignored <control>-T characters that were input in the original 
command during command repetition. IEEE Std. 1003.1-200x prohibits this behavior. 

Find Regular Expression 

Historically, commands did not affect the line searched to or from if the motion command was a 
search (/, ?, N, n) and the final position was the start/end of the line. There were some special 
cases and vi was not consistent. IEEE Std. 1003.1-200x does not permit this behavior, for 
consistency. Historical implementations permitted, but were unable to handle searches as 
motion commands that wrapped (that is, due to the edit option wrapscan) to the original 
location. IEEE Std. 1003.1-200x requires that this behavior be treated as an error. 

Historically, the syntax "/RE/0" was used to force the command to cut text in line mode. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

Historically, in open mode, a z specified to a search command redisplayed the current line 
instead of displaying the current screen with the current line highlighted. For consistency and 
simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 
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Historically, trailing z commands were permitted and ignored if entered as part of a search used 
as a motion command. For consistency and simplicity of specification, IEEE Std. 1003.1-200x 
does not permit this behavior. 

Execute an ex Command 

Historically, vi implementations restricted the commands that could be entered on the colon 
command line (for example, append and change), and some other commands were known to 
cause them to fail catastrophically. For consistency, IEEE Std. 1003.1-200x does not permit these 
restrictions. When executing an ex command by entering :, it is not possible to enter a <newline> 
character as part of the command because it is considered the end of the command. A different 
approach is to enter ex command mode by using the vi Q command (and later resuming visual 
mode with the ex vi command). In ex command mode, the single-line limitation does not exist. 
So, for example, the following is valid: 

Q 

s/break here/break\ 

here/ 

vi 

IEEE Std. 1003.1-200x requires that, if the ex command overwrites any part of the screen that 
would be erased by a refresh, vi pauses for a character from the user. Historically, this character 
could be any character; for example, a character input by the user before the message appeared, 
or even a mapped character. This is probably a bug, but implementations that have tried to be 
more rigorous by requiring that the user enter a specific character, or that the user enter a 
character after the message was displayed, have been forced by user indignation back into 
historical behavior. IEEE Std. 1003.1-200x requires conformance to historical practice. 

Shift Left (Right) 

Refer to the Rationale for the ! and / commands. Historically, the < and > commands sometimes 
moved the cursor to the first non-<blank> character (for example if the command was repeated 
or with _ as the motion command), and sometimes left it unchanged. IEEE Std. 1003.1-200x does 
not permit this inconsistency, requiring instead that the cursor always move to the first non- 
<blank> character. Historically, the < and > commands did not support buffer arguments, 
although some implementations allow the specification of an optional buffer. This behavior is 
neither required nor disallowed by IEEE Std. 1003.1-200x. 

Execute 

Historically, buffers could execute other buffers, and loops, infinite and otherwise, were 
possible. IEEE Std. 1003.1-200x requires conformance to historical practice. The *buffer syntax of 
ex is not required in vi, because it is not historical practice and has been used in some vi 
implementations to support additional scripting languages. 

Historically, vi only supported the " @ @" syntax for repeating the last buffer execution. 
IEEE Std. 1003.1-200x requires that vi support the additional ex syntax " @ *" as well, for 
consistency. 
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41025 Reverse Case 

41026 Historically, the ~ command ignored any associated count, and acted only on the characters in 

41027 the current line. For consistency with other vi commands, IEEE Std. 1003.1-200x requires that an 

41028 associated count act on the next count characters, and that the command move to subsequent 

41029 lines if warranted by count, to make it possible to modify large pieces of text in a reasonably 

41030 efficient manner. There exist vi implementations that optionally require an associated motion 

41031 command for the ~ command. Implementations supporting this functionality are encouraged to 

41032 base it on the tildedop edit option and handle the text regions and cursor positioning identically 

41033 to the yank command. 

41034 Append 

41035 Historically, counts specified to the A, a, I, and i commands repeated the input of the first line 

41036 count times, and did not repeat the subsequent lines of the input text. IEEE Std. 1003.1-200x 

41037 requires that the entire text input be repeated count times. 

41038 Move Backward to Preceding Word 

41039 Historically, vi became confused if word commands were used as motion commands in empty 

41040 files. IEEE Std. 1003.1-200x requires that this be an error. Historical implementations of vi had a 

41041 large number of bugs in the word movement commands, and they varied greatly in behavior in 

41042 the presence of empty lines, "words" made up of a single character, and lines containing only 

41043 <blank> characters. For consistency and simplicity of specification, IEEE Std. 1003.1-200x does 

41044 not permit this behavior. 

41045 Change to End-of-Line 

41046 Some historical implementations of the C command did not behave as described by 

41047 IEEE Std. 1003.1-200x when the $ key was remapped because they were implemented by 

41048 pushing the $ key onto the input queue and reprocessing it. IEEE Std. 1003.1-200x does not 

41049 permit this behavior. Historically, the C, S, and s commands did not copy replaced text into the 

41050 numeric buffers. For consistency and simplicity of specification, IEEE Std. 1003.1-200x requires 

41051 that they behave like their respective c commands in all respects. 

41052 Delete 

41053 Historically, lines in open mode that were deleted were scrolled up, and an @ glyph written over 

41054 the beginning of the line. In the case of terminals that are incapable of the necessary cursor 

41055 motions, the editor erased the deleted line from the screen. IEEE Std. 1003.1-200x requires 

41056 conformance to historical practice; that is, if the terminal cannot display the ' @' character, the 

41057 line cannot remain on the screen. 

41058 Delete to End-of-Line 

41059 Some historical implementations of the D command did not behave as described by 

41060 IEEE Std. 1003.1-200x when the $ key was remapped because they were implemented by 

41061 pushing the $ key onto the input queue and reprocessing it. IEEE Std. 1003.1-200x does not 

41062 permit this behavior. 
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Join 

An historical oddity of vi is that the commands J, 1J, and 2J are all equivalent. 
IEEE Std. 1003.1-200x requires conformance to historical practice. The vi J command is specified 
in terms of the ex join command with an ex command count value. The address correction for a 
count that is past the end of the edit buffer is necessary for historical compatibility for both ex 
and vi. 

Mark Position 

Historical practice is that only lowercase letters, plus ' '' and '' ', could be used to mark a 
cursor position. IEEE Std. 1003.1-200x requires conformance to historical practice, but 
encourages implementations to support other characters as marks as well. 

Repeat Regular Expression Find (Forward and Reverse) 

Historically, the N and n commands could not be used as motion components for the c 
command. With the exception of the cN command, which worked if the search crossed a line 
boundary, the text region would be discarded, and the user would not be in text input mode. For 
consistency and simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 

Insert Empty Fine (Below and Above) 

Historically, counts to the O and o commands were used as the number of physical lines to 
open, if the terminal was dumb and the slowopen option was not set. This was intended to 
minimize traffic over slow connections and repainting for dumb terminals. IEEE Std. 1003.1-200x 
does not permit this behavior, requiring that a count to the open command behave as for other 
text input commands. This change to historical practice was made for consistency, and because a 
superset of the functionality is provided by the slowopen edit option. 

Put from Buffer (Following and Before) 

Historically, counts to the p and P commands were ignored if the buffer was a line mode buffer, 
but were (mostly) implemented as described in IEEE Std. 1003.1-200x if the buffer was a 
character mode buffer. Because implementations exist that do not have this limitation, and 
because pasting lines multiple times is generally useful, IEEE Std. 1003.1-200x requires that count 
be supported for all p and P commands. 

Historical implementations of vi were widely known to have major problems in the p and P 
commands, particularly when unusual regions of text were copied into the edit buffer. The 
standard developers viewed these as bugs, and they are not permitted for consistency and 
simplicity of specification. 

Historically, a P or p command (or an ex put command executed from open or visual mode) 
executed in an empty file, left an empty line as the first line of the file. For consistency and 
simplicity of specification, CA does not permit this behavior. 

Replace Character 

Historically, the r command did not correctly handle the erase and zvord erase characters as 
arguments, nor did it handle an associated count greater than 1 with a <carriage-return> 
character argument, for which it replaced count characters with a single <newline> character. 
IEEE Std. 1003.1-200x does not permit these inconsistencies. 

Historically, the r command permitted the <control>-V escaping of entered characters, such as 
<ESC> and the <carriage-return> character; however, it required two leading <control>-V 
characters instead of one. IEEE Std. 1003.1-200x requires that this be changed for consistency 
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with the other text input commands of vi. 

Historically, it is an error to enter the r command if there are less than count characters at or after 
the cursor in the line. While a reasonable and unambiguous extension would be to permit the r 
command on empty lines, it would require that too large a count be adjusted to match the 
number of characters at or after the cursor for consistency, which is sufficiently different from 
historical practice to be avoided. IEEE Std. 1003.1-200x requires conformance to historical 
practice. 

Replace Characters 

Historically, if there were autoindent characters in the line on which the R command was run, 
and autoindent was set, the first <newline> character would be properly indented and no 
characters would be replaced by the <newline> character. Each additional <newline> character 
would replace n characters, where n was the number of characters that were needed to indent 
the rest of the line to the proper indentation level. This behavior is a bug and is not permitted by 
IEEE Std. 1003.1-200x. 

Undo 

Historical practice for cursor positioning after undoing commands was mixed. In most cases, 
when undoing commands that affected a single line, the cursor was moved to the start of added 
or changed text, or immediately after deleted text. However, if the user had moved from the line 
being changed, the column was either set to the first non-<blank> character, returned to the 
origin of the command, or remained unchanged. When undoing commands that affected 
multiple lines or entire lines, the cursor was moved to the first character in the first line restored. 
As an example of how inconsistent this was, a search, followed by an o text input command, 
followed by an undo would return the cursor to the location where the o command was entered, 
but a cw command followed by an o command followed by an undo would return the cursor to 
the first non-<blank> character of the line. IEEE Std. 1003.1-200x requires the most useful of 
these behaviors, and discards the least useful, in the interest of consistency and simplicity of 
specification. 

Yank 

Historically, the yank command did not move to the end of the motion if the motion was in the 
forward direction. It moved to the end of the motion if the motion was in the backward 
direction, except for the _ command, or for the G and ' commands when the end of the motion 
was on the current line. This was further complicated by the fact that for a number of motion 
commands, the yank command moved the cursor but did not update the screen; for example, a 
subsequent command would move the cursor from the end of the motion, even though the 
cursor on the screen had not reflected the cursor movement for the yank command. 
IEEE Std. 1003.1-200x requires that all yank commands associated with backward motions move 
the cursor to the end of the motion for consistency, and specifically, to make ' commands as 
motions consistent with search patterns as motions. 
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Yank Current Line 

Some historical implementations of the Y command did not behave as described by 
IEEE Std. 1003.1-200x when the ' key was remapped because they were implemented by 
pushing the ' key onto the input queue and reprocessing it. IEEE Std. 1003.1-200x does not 
permit this behavior. 

Redraw Window 

Historically, the z command always redrew the screen. This is permitted but not required by 
IEEE Std. 1003.1-200x, because of the frequent use of the z command in macros such as map n 
nz. for screen positioning, instead of its use to change the screen size. The standard developers 
believed that expanding or scrolling the screen offered a better interface for users. The ability to 
redraw the screen is preserved if the optional new window size is specified, and in the 
<control>-L and <control>-R commands. 

The semantics of z' are confusing at best. Historical practice is that the screen before the screen 
that ended with the specified line is displayed. IEEE Std. 1003.1-200x requires conformance to 
historical practice. 

Historically, the z command would not display a partial line at the top or bottom of the screen. If 
the partial line would normally have been displayed at the bottom of the screen, the command 
worked, but the partial line was replaced with ' @' characters. If the partial line would normally 
have been displayed at the top of the screen, the command would fail. For consistency and 
simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, the z command with a line specification of 1 ignored the command. For consistency 
and simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 

Historically, the z command did not set the cursor column to the first non-<blank> character for 
the character if the first screen was to be displayed, and was already displayed. For consistency 
and simplicity of specification, IEEE Std. 1003.1-200x does not permit this behavior. 

Input Mode Commands in vi 

Historical implementations of vi did not permit the the user to erase more than a single line of 
input, or to use normal erase characters such as line erase, worderase, and erase to erase 
autoindent characters. As there exist implementations of vi that do not have these limitations, 
both behaviors are permitted, but only historical practice is required. In the case of these 
extensions, vi is required to pause at the autoindent and previous line boundaries. 

Historical implementations of vi updated only the portion of the screen where the current cursor 
character was displayed. For example, consider the vi input keystrokes: 

iabcd<escape>OC<tab> 

Historically, the <tab> character would overwrite the characters "abed" when it was displayed. 
Other implementations replace only the ' a' character with the <tab> character, and then push 
the rest of the characters ahead of the cursor. Both implementations have problems. The 
historical implementation is probably visually nicer for the above example; however, for the 
keystrokes: 

iabcd<ESC>OR<tab><ESC> 

the historical implementation results in the string "bed" disappearing and then magically 
reappearing when the <ESC> character is entered. IEEE Std. 1003.1-200x requires the former 
behavior when overwriting erase-columns; that is, overwriting characters that are no longer 
logically part of the edit buffer, and the latter behavior otherwise. 
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Historical implementations of vi discarded the <control>-D and <control>-T characters when 
they were entered at places where their command functionality was not appropriate. 
IEEE Std. 1003.1-200x requires that the <control>-T functionality always be available, and that 
<control>-D be treated as any other key when not operating on autoindent characters. 

NUL 

Some historical implementations of vi limited the number of characters entered using the NUL 
input character to 256 bytes. IEEE Std. 1003.1-200x permits this limitation; however, 
implementations are encouraged to remove this limit. 

<control>-D 

See also Rationale for the input mode command <newline>. The hidden assumptions in the 
<control>-D command (and in the vi autoindent specification in general) is that <space> 
characters take up a single column on the screen and that <tab> characters are comprised of an 
integral number of <space> characters. 

<newline> 

Implementations are permitted to rewrite autoindent characters in the line when <newline>, 
<carriage-return>, <control>-D, and <control>-T are entered, or when the shift commands are 
used, because historical implementations have both done so and found it necessary to do so. For 
example, a <control>-D when the cursor is preceded by a single <tab> character, with tabstop 
set to 8, and shiftwidth set to 3, will result in the <tab> character being replaced by several 
<space> characters. 

<control>-T 

See also the Rationale for the input mode command <newline>. Historically, <control>-T only 
worked if no non-<blank> characters had yet been input in the current input line. In addition, 
the characters inserted by <control>-T were treated as autoindent characters, and could not be 
erased using normal user erase characters. Because implementations exist that do not have 
these limitations, and as moving to a column boundary is generally useful, IEEE Std. 1003.1-200x 
requires that both limitations be removed. 

<control>-V 

Historically, vi used "V, regardless of the value of the literal-next character of the terminal. 
IEEE Std. 1003.1-200x requires conformance to historical practice. 

The uses described for <control>-V can also be accomplished with <control>-Q, which is useful 
on terminals that use <control>-V for the down-arrow function. However, most historical 
implementations use <control>-Q for the termios START character, so the editor will generally 
not receive the <control>-Q unless stty ixon mode is set to off. (In addition, some historical 
implementations of vi explicitly set ixon mode to on, so it was difficult for the user to set it to 
off.) Any of the command characters described in IEEE Std. 1003.1-200x can be made ineffective 
by their selection as termios control characters, using the stty utility or other methods described 
in the System Interfaces volume of IEEE Std. 1003.1-200x. 
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<ESC> I 

Historically, SIGINT alerted the terminal when used to end input mode. This behavior is I 
permitted, but not required, by IEEE Std. 1003.1-200x. I 

FUTURE DIRECTIONS 

None. I 

SEE ALSO 

ex, stty I 

CHANGE HISTORY 

First released in Issue 2. 

Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

FUTURE DIRECTIONS section added. 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 

The APPLICATION USAGE section is added. 

The obsolescent SYNOPSIS is removed. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• Lisp mode is added. I 

• The reindent command description is added. I 

The vi utility has been extensively rewritten for alignment with the IEEE P1003.2b draft I 
standard. I 
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NAME 

wait — await process completion 

SYNOPSIS 

wait [pid...] 

DESCRIPTION 

When an asynchronous list (see Section 2.9.3.1 on page 74) is started by the shell, the process ID 
of the last command in each element of the asynchronous list shall become known in the current 
shell execution environment; see Section 2.12 on page 90. 

If the wait utility is invoked with no operands, it shall wait until all process IDs known to the 
invoking shell have terminated and exit with a zero exit status. 

If one or more pid operands are specified that represent known process IDs, the wait utility shall 
wait until all of them have terminated. If one or more pid operands are specified that represent 
unknown process IDs, wait shall treat them as if they were known process IDs that exited with 
exit status 127. The exit status returned by the wait utility shall be the exit status of the process 
requested by the last pid operand. 

The known process IDs are applicable only for invocations of wait in the current shell execution 
environment. 

OPTIONS 

None. 

OPERANDS 

The following operand shall be supported: 
pid One of the following: 

1. The unsigned decimal integer process ID of a command, for which the utility 
is to wait for the termination. 

2. A job control job ID (see the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 3.207, Job Control Job ID) that identifies a I 
background process group to be waited for. The job control job ID notation is I 
applicable only for invocations of wait in the current shell execution 
environment; see Section 2.12 on page 90. The exit status of wait shall be 
determined by the last command in the pipeline. 

Note: The job control job ID type of pid is only available on systems 

supporting the User Portability Utilities option. 

STDIN 

Not used. 

INPUT FILES 

None. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of wait: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 
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41293 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


41294 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

41295 characters (for example, single-byte as opposed to multi-byte characters in 

41296 arguments). 

41297 LC_MESSAGES 

41298 Determine the locale that should be used to affect the format and contents of 

41299 diagnostic messages written to standard error. 

41300 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

41301 ASYNCHRONOUS EVENTS 

41302 Default. 


41303 STDOUT 

41304 Not used. 


41305 STDERR 

41306 Used only for diagnostic messages. 

41307 OUTPUT FILES 

41308 None. 


41309 EXTENDED DESCRIPTION 

41310 None. 


41311 EXIT STATUS 

41312 If one or more operands were specified, all of them have terminated or were not known by the 

41313 invoking shell, and the status of the last operand specified is known, then the exit status of zvait 

41314 shall be the exit status information of the command indicated by the last operand specified. If 

41315 the process terminated abnormally due to the receipt of a signal, the exit status shall be greater 

41316 than 128 and shall be distinct from the exit status generated by other signals, but the exact value 

41317 is unspecified. (See the kill -1 option.) Otherwise, the zvait utility shall exit with one of the 

41318 following values: 


41319 0 The wait utility was invoked with no operands and all process IDs known by the 

41320 invoking shell have terminated. 


41321 1-126 The zvait utility detected an error. 

41322 127 The command identified by the last pid operand specified is unknown. 


41323 CONSEQUENCES OF ERRORS 

41324 Default. 

41325 APPLICATION USAGE 

41326 On most implementations, zvait is a shell built-in. If it is called in a subshell or separate utility 

41327 execution environment, such as one of the following: 

41328 (wait) 

41329 nohup wait . . . 

41330 find . —exec wait ... \; 

41331 it returns immediately because there are no known process IDs to wait for in those 

41332 environments. 

41333 Historical implementations of interactive shells have discarded the exit status of terminated 

41334 background processes before each shell prompt. Therefore, the status of background processes 

41335 was usually lost unless it terminated while zvait was waiting for it. This could be a serious 
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41336 

41337 

41338 

41339 

41340 

41341 

41342 

41343 

41344 

41345 

41346 

41347 

41348 

41349 

41350 

41351 

41352 

41353 

41354 

41355 

41356 

41357 

41358 

41359 

41360 

41361 

41362 

41363 

41364 

41365 

41366 

41367 

41368 

41369 

41370 

41371 

41372 

41373 

41374 

41375 

41376 

41377 

41378 

41379 

41380 

41381 

41382 


problem when a job that was expected to run for a long time actually terminated quickly with a 
syntax or initialization error because the exit status returned was usually zero if the requested 
process ID was not found. This volume of IEEE Std. 1003.1-200x requires the implementation to 
keep the status of terminated jobs available until the status is requested, so that scripts like: 

jl& 
pl = $ ! 
j2& 

wait $pl 

echo Job 1 exited with status $? 
wait $! 

echo Job 2 exited with status $? 

works without losing status on any of the jobs. The shell is allowed to discard the status of any 
process that it determines the application cannot get the process ID from the shell. It is also 
required to remember only |CHILD_MAX} number of processes in this way. Since the only way 
to get the process ID from the shell is by using the ' !' shell parameter, the shell is allowed to 
discard the status of an asynchronous list if " $!" was not referenced before another 
asynchronous list was started. (This means that the shell only has to keep the status of the last 
asynchronous list started if the application did not reference " $ ! ". If the implementation of the 
shell is smart enough to determine that a reference to " $ !" was not saved anywhere that the 
application can retrieve it later, it can use this information to trim the list of saved information. 
Note also that a successful call to wait with no operands discards the exit status of all 
asynchronous lists.) 

If the exit status of wait is greater than 128, there is no way for the application to know if the 
waited-for process exited with that value or was killed by a signal. Since most utilities exit with 
small values, there is seldom any ambiguity. Even in the ambiguous cases, most applications 
just need to know that the asynchronous job failed; it does not matter whether it detected an 
error and failed or was killed and did not complete its job normally. 

EXAMPLES 

Although the exact value used when a process is terminated by a signal is unspecified, if it is 
known that a signal terminated a process, a script can still reliably figure out which signal using 
kill as shown by the following script: 

sleep 1000& 
pid=$! 

kill —kill $pid 
wait $pid 

echo $pid was terminated by a SIG$(kill —1 $?) signal. 

If the following sequence of commands is run in less than 31 seconds: 

sleep 257 | sleep 31 & 
jobs —1 %% 

either of the following commands returns the exit status of the second sleep in the pipeline: 

wait <pid of sleep 31> 
wait %% 

RATIONALE 

The description of wait does not refer to the ivaitpid() function from the System Interfaces 
volume of IEEE Std. 1003.1-200x because that would needlessly overspecify this interface. 
However, the wording means that wait is required to wait for an explicit process when it is given 
an argument so that the status information of other processes is not consumed. Historical 
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41384 

41385 

41386 

41387 

41388 

41389 

41390 

41391 

41392 

41393 

41394 

41395 

41396 

41397 

41398 

41399 

41400 

41401 

41402 

41403 

41404 

41405 


implementations use The zvait() function defined in the System Interfaces volume of 
IEEEStd. 1003.1-200x until wait () returns the requested process ID or finds that the requested 
process does not exist. Because this means that a shell script could not reliably get the status of 
all background children if a second background job was ever started before the first job finished, 
it is recommended that the wait utility use a method such as the functionality provided by the 
zvaitpid () function. 

The ability to wait for multiple pid operands was adopted from the KomShell. 

This new functionality was added because it is needed to determine the exit status of any 
asynchronous list accurately. The only compatibility problem that this change creates is for a 
script like 

while sleep 60 do 

jobs echo Job started $(date) as $! done 

which causes the shell to monitor all of the jobs started until the script terminates or runs out of I 
memory. This would not be a problem if the loop did not reference " $ ! " or if the script would 
occasionally zvait for jobs it started. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

sh, the System Interfaces volume of IEEE Std. 1003.1-200x, zvaitpid () 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 


Commands and Utilities, Issue 6 


1087 



wc 


Utilities 


41406 NAME 

41407 wc — word, line, and byte or character count 

41408 SYNOPSIS 

41409 wc [—c|—m] [—lw] [file. . .] 

41410 DESCRIPTION 

41411 The zvc utility shall read one or more input files and, by default, write the number of <newline> 

41412 characters, words, and bytes contained in each input file to the standard output. 

41413 The utility also shall write a total count for all named files, if more than one input file is 

41414 specified. 

41415 The zvc utility shall consider a zvord to be a non-zero-length string of characters delimited by 

41416 white space. 

41417 OPTIONS 

41418 The zvc utility shall conform to the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

41419 Section 12.2, Utility Syntax Guidelines. I 

41420 The following options shall be supported: 

41421 -c Write to the standard output the number of bytes in each input file. 

41422 -1 Write to the standard output the number of <newline> characters in each input 

41423 file. 

41424 -m Write to the standard output the number of characters in each input file. 

41425 -w Write to the standard output the number of words in each input file. 

41426 When any option is specified, zvc shall report only the information requested by the specified 

41427 options. 

41428 OPERANDS 

41429 The following operand shall be supported: 

41430 file A path name of an input file. If no file operands are specified, the standard input 

41431 shall be used. 

41432 STDIN 

41433 The standard input shall be used only if no file operands are specified. See the INPUT FILES 

41434 section. 

41435 INPUT FILES 

41436 The input files may be of any type. 

41437 ENVIRONMENT VARIABLES 

41438 The following environment variables shall affect the execution of zvc: 

41439 LANG Provide a default value for the internationalization variables that are unset or null. 

41440 If LANG is unset or null, the corresponding value from the implementation- 

41441 dependent default locale shall be used. If any of the internationalization variables 

41442 contains an invalid setting, the utility shall behave as if none of the variables had 

41443 been defined. 

41444 LC_ALL If set to a non-empty string value, override the values of all the other 

41445 internationalization variables. 

41446 LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 

41447 characters (for example, single-byte as opposed to multi-byte characters in 

41448 arguments and input files) and which characters are defined as white space 
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41451 

41452 

41453 

41454 

41455 

41456 

41457 

41458 

41459 

41460 

41461 

41462 

41463 

41464 

41465 

41466 

41467 

41468 

41469 

41470 

41471 

41472 

41473 

41474 

41475 

41476 

41477 

41478 

41479 

41480 

41481 

41482 

41483 

41484 

41485 


characters. 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error and informative messages written to 
standard output. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

By default, the standard output shall contain an entry for each input file of the form: 

"%d %d %d %s\n", <newlines>, <words>, <bytes>, <file> 

If the -m option is specified, the number of characters shall replace the <bytes> field in this 
format. 

If any options are specified and the -1 option is not specified, the number of <newline> 
characters shall not be written. 

If any options are specified and the -w option is not specified, the number of words shall not be 
written. 

If any options are specified and neither -c nor -m is specified, the number of bytes or characters 
shall not be written. 

If no input file operands are specified, no name shall be written and no <blank> characters 
preceding the path name shall be written. 

If more than one input file operand is specified, an additional line shall be written, of the same 
format as the other lines, except that the word total (in the POSIX locale) shall be written instead 
of a path name and the total of each column shall be written as appropriate. Such an additional 
line, if any, is written at the end of the output. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 
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41486 APPLICATION USAGE 

41487 The -m option is not a switch, but an option at the same level as -c. Thus, to produce the full 

41488 default output with character counts instead of bytes, the command required is: 

41489 wc —mlw 

41490 EXAMPLES 

41491 None. 

41492 RATIONALE 

41493 The output file format pseudo -printf( ) string differs from the the System V version of wc: 

41494 "%7d%7d%7d %s\n" 

41495 which produces possibly ambiguous and unparsable results for very large files, as it assumes no 

41496 number shall exceed six digits. 

41497 Some historical implementations use only <space>, <tab>, and <newline> as word separators. 

41498 The equivalent of the ISO C standard isspace( ) function is more appropriate. 

41499 The -c option stands for "character" count, even though it counts bytes. This stems from the 

41500 sometimes erroneous historical view that bytes and characters are the same size. Due to 

41501 international requirements, the -m option (reminiscent of "multi-byte") was added to obtain 

41502 actual character counts. 

41503 Early proposals only specified the results when input files were text files. The current 

41504 specification more closely matches historical practice. (Bytes, words, and <newline>s are 

41505 counted separately and the results are written when an end-of-file is detected.) 

41506 Historical implementations of the zvc utility only accepted one argument to specify the options 

41507 -c, -1, and -w. Some of them also had multiple occurrences of an option cause the 

41508 corresponding count to be written multiple times and had the order of specification of the 

41509 options affect the order of the fields on output, but did not document either of these. Because 

41510 common usage either specifies no options or only one option, and because none of this was 

41511 documented, the changes required by this volume of IEEE Std. 1003.1-200x should not break 

41512 many historical applications (and do not break any historical portable applications). 

41513 FUTURE DIRECTIONS 

41514 None. 

41515 SEE ALSO 

41516 cksum 

41517 CHANGE HISTORY 

41518 First released in Issue 2. 

41519 Issue 4 

41520 Aligned with the ISO/IEC 9945-2:1993 standard. 
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41521 NAME 

41522 what — identify SCCS files (DEVELOPMENT) 

41523 SYNOPSIS 

41524 xsi what [—s] file. . . 

41525 

41526 DESCRIPTION 

41527 The zvhat utility shall search the given files for all occurrences of the pattern that get (see get on 

41528 P a g e 510) substitutes for %Z% ("@ (#) ") and shall write to standard output what follows until 

41529 the first occurrence of one of the following: 

41530 " > newline \ NUL 

41531 OPTIONS 

41532 The zvhat utility shall conform to the System Interface Definitions volume of I 

41533 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

41534 The following option is supported: 

41535 -s Quit after finding the first occurrence of the pattern in each file. 

41536 OPERANDS 

41537 The following operands shall be supported: 

41538 file A path name of a file to search. 

41539 STDIN 

41540 Not used. 


41541 INPUT FILES 

41542 The input files are of any file type. 


41543 ENVIRONMENT VARIABLES 

41544 The following environment variables shall affect the execution of zvhat: 


41545 

41546 

41547 

41548 

41549 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


41550 LC_ALL If set to a non-empty string value, override the values of all the other 

41551 internationalization variables. 


41552 

41553 

41554 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 


41555 

41556 

41557 


LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


41558 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


41559 ASYNCHRONOUS EVENTS 

41560 Default. 
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41561 STDOUT 

41562 The standard output shall consist of the following for each file operand: 

41563 "%s : \n\t%s\n" , <pathname>, <identification string> 

41564 STDERR 

41565 Used only for diagnostic messages. 

41566 OUTPUT FILES 

41567 None. 

41568 EXTENDED DESCRIPTION 

41569 None. 

41570 EXIT STATUS 

41571 The following exit values shall be returned: 

41572 0 Any matches were found. 

41573 1 Otherwise. 

41574 CONSEQUENCES OF ERRORS 

41575 Default. 

41576 APPLICATION USAGE 

41577 The zvluit utility is intended to be used in conjunction with the SCCS command get, which 

41578 automatically inserts identifying information, but it can also be used where the information is 

41579 inserted by any other means. 

41580 When the string " @ (#) " is included in a library routine in a shared library, it might not be found 

41581 in an a.out file using that library routine. 

41582 EXAMPLES 

41583 If the C-language program in file f.c contains: 

41584 char ident [ ] = "@ (#) identification information"; 

41585 and f.c is compiled to yield f.o and a.out, then the command: 

41586 what f.c f.o a . out 

41587 writes: 

41588 f.c: 

41589 identification information 

41590 

41591 f.o: 

41592 identification information 

41593 

41594 a . out : 

41595 identification information 

41596 

41597 RATIONALE 

41598 None. 

41599 FUTURE DIRECTIONS 

41600 None. 
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41601 SEE ALSO 

41602 get 

41603 CHANGE HISTORY 

41604 First released in Issue 2. 

41605 Issue 4 

41606 Format reorganized. 

41607 Utility Syntax Guidelines support mandated. 

41608 Internationalized environment variable support mandated. 
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41609 NAME 

41610 who — display who is on the system 

41611 SYNOPSIS 

41612 UP who [—mTu] 

41613 

41614 xsi who [—mu] —s [—bHlprt ][ file] 

41615 who [-mTu] [—abdHlprt] [file] 

41616 who — q [file] 

41617 who am i 

41618 who am I 

41619 


41620 DESCRIPTION 

41621 The zvho utility shall list various pieces of information about accessible users. The domain of 

41622 accessibility is implementation-dependent. 

41623 xsi Based on the options given, zvho can also list the user's name, terminal line, login time, elapsed 

41624 time since activity occurred on the line, and the process ID of the command interpreter for each 

41625 current system user. 


41626 OPTIONS 

41627 The zvho utility shall conform to the System Interface Definitions volume of I 

41628 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

41629 The following options shall be supported. The metavariables, such as <line>, refer to fields 

41630 described in the STDOUT section. 


41631 xsi -a Process the implementation-dependent database or named file with the -b, -d, -1, 

41632 -p, -r, -t, -T and -u options turned on. 


41633 XSI -b 


Write the time and date of the last reboot. 


41634 XSI 

41635 

41636 

41637 


-d Write a list of all processes that have expired and not been respawned by the init 

system process. The <exit> field appears for dead processes and contains the 
termination and exit values of the dead process. This can be useful in determining 
why a process terminated. 


41638 XSI 

41639 XSI 

41640 

41641 


-H Write column headings above the regular output. 

-1 (The letter ell.) List only those lines on which the system is waiting for someone to 

login. The <name> field is LOGIN in such cases. Other fields are the same as for 
user entries except that the <state> field does not exist. 


41642 


-m Output only information about the current terminal. 


41643 xsi -p List any other process that is currently active and has been previously spawned by 

41644 init. 


41645 XSI 

41646 

41647 XSI 

41648 XSI 

41649 XSI 


-q (Quick.) List only the names and the number of users currently logged on. When 


this option is used, all other options are ignored. 


-r Write the current run-level of the init process. 


-s List only the <name>, <line>, and <time> fields. This is the default case. 

-t Indicate the last change to the system clock. 
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41650 


-T Show the state of each terminal, as described in the STDOUT section. 


41651 XSI -U 

41652 

41653 

41654 XSI 

41655 

41656 

41657 

41658 

41659 

41660 

41661 


This option lists only those users who are currently logged in. Output the user's 
"idle time" in addition to any other information. The idle time is the time since 
any activity occurred on the user's terminal. The method of determining this is 
unspecified. The <name> is the user's login name. The <line> is the name of the line 
as found in the directory /dev. The <time> is the time that the user logged in. The 
<activity> is the number of hours and minutes since activity last occurred on that 
particular line. A dot indicates that the terminal has seen activity in the last minute 
and is therefore "current". If more than twenty-four hours have elapsed or the line 
has not been used since boot time, the entry is marked <old>. This field is useful 
when trying to determine whether a person is working at the terminal or not. The 
<pid> is the process ID of the user's login process. 


41662 OPERANDS 

41663 xsi The following operands shall be supported: 

41664 

41665 

41666 file Specify a path name of a file to substitute for the implementation-dependent 

41667 database of logged-on users that who uses by default. 


am i, am I In the POSIX locale, limit the output to describing the invoking user, equivalent to 
the -m option. The am and i or I must be separate arguments. 


41668 STDIN 

41669 Not used. 


41670 INPUT FILES 

41671 None. 


41672 ENVIRONMENT VARIABLES 


41673 

The following environment variables shall affect the execution of who: 

41674 

41675 

41676 

41677 

41678 

LANG 

Provide a default value for the internationalization variables that are unset or null. 
If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

41679 

41680 

LC_ALL 

If set to a non-empty string value, override the values of all the other 
internationalization variables. 

41681 

41682 

41683 

LCjCTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 

41684 

41685 

41686 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

41687 

LCJTIME 

Determine the locale used for the format and contents of the date and time strings. 

41688 XSI 

NLSPATH 

Determine the location of message catalogs for the processing of LC_MESSAGES. 


41689 ASYNCHRONOUS EVENTS 

41690 Default. 
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41691 

41692 

41693 

41694 

41695 

41696 

41697 

41698 

41699 

41700 

41701 

41702 

41703 

41704 

41705 

41706 

41707 

41708 

41709 

41710 

41711 

41712 

41713 

41714 

41715 

41716 

41717 

41718 

41719 

41720 

41721 

41722 

41723 

41724 

41725 

41726 

41727 

41728 

41729 

41730 

41731 


STDOUT 

xsi of XSI-conformant systems shall write the default information to the standard output in the 
following general format: 

<name>[<state>]<line><time>[<activity>] [<pid>][ <comment> ][<exit>] 

The following format shall be used for the -T option: 

"%s %c %s %s\n" <name>, <terminal state>, <terminal name >, 

<time of login> 

where <terminal staff> is one of the following characters: 

+ The terminal allows write access to other users. 

- The terminal denies write access to other users. 

? The terminal write-access state cannot be determined. 

In the POSIX locale, the <time oflogin> shall be equivalent in format to the output of: 

date +"%b %e %H:%M" 

If the -u option is used with -T, the idle time shall be added to the end of the previous format in 
an unspecified format. 

STDERR 

Used only for diagnostic messages. 

OUTPUT FILES 

None. 

EXTENDED DESCRIPTION 

None. 

EXIT STATUS 

The following exit values shall be returned: 

0 Successful completion. 

>0 An error occurred. 

CONSEQUENCES OF ERRORS 
Default. 

APPLICATION USAGE 

The name init used for the system process is the most commonly used on historical systems, but 
it may vary. 

The "domain of accessibility" referred to is a broad concept that permits interpretation either on 
a very secure basis or even to allow a network-wide implementation like the historical rzvho. 

Application writers should note that this utility need not be provided on systems that do not 
support the User Portability Utilities option. 

EXAMPLES 

None. 

RATIONALE 

Due to differences between historical implementations, the base options provided were a 
compromise to allow users to work with those functions. The standard developers also 
considered removing all the options, but felt that these options offered users valuable 
functionality. Additional options to match historical systems are available on XSI-conformant 
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41732 

41733 

41734 

41735 

41736 

41737 

41738 

41739 

41740 

41741 

41742 

41743 

41744 

41745 

41746 

41747 

41748 

41749 

41750 


systems. 

It is recognized that the zvho command may be of limited usefulness, especially in a multi-level 
secure environment. The standard developers considered, however, that having some standard 
method of determining the "accessibility" of other users would aid user portability. 

No format was specified for the default zvho output for systems not supporting the XSI 
Extension. In such a user-oriented command, designed only for human use, this was not 
considered to be a deficiency. 

The format of the terminal name is unspecified, but the descriptions of ps, talk, and write require 
that they use the same format. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mesg 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 6 

This utility is now marked as part of the User Portability Utilities option. 
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41751 NAME 

41752 write — write to another user 

41753 SYNOPSIS 

41754 up write user_name [terminal ] 

41755 

41756 DESCRIPTION 

41757 The write utility shall read lines from the user 7 s standard input and write them to the terminal of 

41758 another user. When first invoked, it shall write the message: 

41759 Message from sender-login-id ( sending-terminal ) [date] . . . 

41760 to user_name. When it has successfully completed the connection, the sender's terminal shall be 

41761 alerted twice to indicate that what the sender is typing is being written to the recipient's 

41762 terminal. 

41763 If the recipient wants to reply, this can be accomplished by typing: 

41764 write sender-login-id [sending-terminal] 

41765 upon receipt of the initial message. Whenever a line of input as delimited by a NL, EOF, or EOL I 

41766 special character (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter I 

41767 11, General Terminal Interface) is accumulated while in canonical input mode, the accumulated I 

41768 data shall be written on the other user's terminal. Characters shall be processed as follows: 

41769 • Typing the <alert> character shall write the alert character to the recipient's terminal. 

41770 • Typing the erase and kill characters shall affect the sender's terminal in the manner described 

41771 by the termios interface in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

41772 Chapter 11, General Terminal Interface. I 

41773 • Typing the interrupt or end-of-file characters shall cause write to write an appropriate 

41774 message (" EOT\n" in the POSIX locale) to the recipient's terminal and exit. 

41775 • Typing characters from LC_CTYPE classifications print or space shall cause those characters 

41776 to be sent to the recipient's terminal. 

41777 • When and only when the stty iexten local mode is enabled, the existence and processing of 

41778 additional special control characters and multi-byte or single-byte functions is 

41779 implementation-dependent. 

41780 • Typing other non-printable characters shall cause implementation-dependent sequences of 

41781 printable characters to be written to the recipient's terminal. 

41782 To write to a user who is logged in more than once, the terminal argument can be used to indicate 

41783 which terminal to write to; otherwise, the recipient's terminal is selected in an implementation- 

41784 dependent manner and an informational message is written to the sender's standard output, 

41785 indicating which terminal was chosen. 

41786 Permission to be a recipient of a write message can be denied or granted by use of the mesg 

41787 utility. However, a user's privilege may further constrain the domain of accessibility of other 

41788 users' terminals. The write utility shall fail when the user lacks the appropriate privileges to 

41789 perform the requested action. 

41790 OPTIONS 

41791 None. 
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41792 OPERANDS 

41793 The following operands shall be supported: 

41794 user_name Login name of the person to whom the message shall be written. The application I 

41795 shall ensure that this operand is of the form returned by the who utility. I 

41796 terminal Terminal identification in the same format provided by the zvho utility. 

41797 STDIN 

41798 Lines to be copied to the recipient's terminal is read from standard input. 

41799 INPUT FILES 

41800 None. 


41801 ENVIRONMENT VARIABLES 

41802 The following environment variables shall affect the execution of write-. 


41803 

41804 

41805 

41806 

41807 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


41808 

41809 


LC_ALL 


If set to a non-empty string value, override the values of all the other 
internationalization variables. 


41810 

41811 

41812 

41813 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). If the recipient's locale does not use an LC_CTYPE 
equivalent to the sender's, the results are undefined. 


41814 LC_MESSAGES 

41815 Determine the locale that should be used to affect the format and contents of 

41816 diagnostic messages written to standard error and informative messages written to 

41817 standard output. 

41818 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


41819 ASYNCHRONOUS EVENTS 

41820 If an interrupt signal is received, write shall write an appropriate message on the recipient's 

41821 terminal and exits with a status of zero. It shall take the standard action for all other signals. 


41822 STDOUT 

41823 An informational message shall be written to standard output if a recipient is logged in more 

41824 than once. 


41825 STDERR 

41826 Used only for diagnostic messages. 

41827 OUTPUT FILES 

41828 The recipient's terminal is used for output. 

41829 EXTENDED DESCRIPTION 

41830 None. 


41831 EXIT STATUS 

41832 The following exit values shall be returned: 

41833 0 Successful completion. 
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41834 >0 The addressed user is not logged on or the addressed user denies permission. 

41835 CONSEQUENCES OF ERRORS 

41836 Default. 

41837 APPLICATION USAGE 

41838 The talk utility is considered by some users to be a more usable utility on full-screen terminals. 

41839 Application writers should note that this utility need not be provided on systems that do not 

41840 support the User Portability Utilities option. 

41841 EXAMPLES 

41842 None. 

41843 RATIONALE 

41844 The ivrite utility was included in this volume of IEEE Std. 1003.1-200x since it can be 

41845 implemented on all terminal types. The standard developers considered the talk utility, which 

41846 cannot be implemented on certain terminals, to be a "better" communications interface. Both of 

41847 these programs are in widespread use on historical implementations. Therefore, the standard 

41848 developers decided that both utilities should be specified. 

41849 The format of the terminal name is unspecified, but the descriptions of ps, talk, who, and write 

41850 require that they all use or accept the same format. 

41851 FUTURE DIRECTIONS 

41852 None. I 

41853 SEE ALSO 

41854 mesg, talk, who, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 11, I 

41855 General Terminal Interface I 

41856 CHANGE HISTORY 

41857 First released in Issue 2. 

41858 Issue 4 

41859 Aligned with the ISO/IEC 9945-2:1993 standard. 

41860 Issue 5 

41861 FUTURE DIRECTIONS section added. 

41862 Issue 6 

41863 This utility is now marked as part of the User Portability Utilities option. I 

41864 The normative text is reworded to avoid use of the term "must" for application requirements. I 
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41865 

41866 

41867 

41868 

41869 

41870 

41871 

41872 

41873 

41874 

41875 

41876 

41877 

41878 

41879 

41880 

41881 

41882 

41883 

41884 

41885 

41886 

41887 

41888 

41889 

41890 

41891 

41892 

41893 

41894 

41895 

41896 

41897 

41898 

41899 

41900 

41901 

41902 

41903 

41904 

41905 

41906 

41907 

41908 

41909 

41910 

41911 


NAME 

xargs — construct argument lists and invoke utility 

SYNOPSIS 

xsi xargs [—t] [— p] ] [—E eofstr ] [—1 replstr] [—L number ] [—n number [—x] ] | 

[—s size][utility [argument...]] \ 

DESCRIPTION 

The xargs utility shall construct a command line consisting of the utility and argument operands 
specified followed by as many arguments read in sequence from standard input as fit in length 
and number constraints specified by the options. The xargs utility shall then invoke the 
constructed command line and wait for its completion. This sequence shall be repeated until one I 
of the following occurs: I 

• An end-of-file condition is detected on standard input. I 

• The logical end-of-file string (see the -E eofstr option) is found on standard input after I 

double-quote processing, apostrophe processing, and backslash escape processing (see next I 
paragraph). I 

• An invocation of a constructed command line returns an exit status of 255. I 

The application shall ensure that arguments in the standard input are separated by unquoted I 
<blank> characters, or unescaped <blank> characters or <newline> characters. A string of zero 
or more non-double-quote (' ) ' and non-<newline> characters can be quoted by enclosing 

them in double-quotes. A string of zero or more non-apostrophe (' ' ') and non-<newline> I 
characters can be quoted by enclosing them in apostrophes. Any unquoted character can be I 
escaped by preceding it with a backslash. The utility shall be executed one or more times until I 
the end-of-file is reached or the logical end-of file string is found. The results are unspecified if I 
the utility named by utility attempts to read from its standard input. I 

The generated command line length shall be the sum of the size in bytes of the utility name and 
each argument treated as strings, including a null byte terminator for each of these strings. The 
xargs utility shall limit the command line length such that when the command line is invoked, 
the combined argument and environment lists (see the exec family of functions in the System 
Interfaces volume of IEEE Std. 1003.1-200x) shall not exceed {ARG_MAX}-2 048 bytes. Within 
this constraint, if neither the -n nor the -s option is specified, the default command line length 
shall be at least {LINE_MAX}. 

OPTIONS 

The xargs utility shall conform to the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 

The following options shall be supported: 

xsi -E eofstr Use eofstr as the logical end-of-file string. If -E is not specified, it is unspecified I 

whether the logical end-of-file string is the underscore character (' ) or the end- I 

of-file string capability is disabled. When eofstr is the null string, the logical end- I 

of-file string capability shall be disabled and underscore characters shall be taken I 

literally. I 

xsi -I replstr Insert mode: utility is executed for each line from standard input, taking the entire 

line as a single argument, inserting it in arguments for each occurrence of replstr. A 
maximum of five arguments in arguments can each contain one or more instances 
of replstr. Any <blank> characters at the beginning of each line shall be ignored. 
Constructed arguments cannot grow larger than 255 bytes. Option -x is forced on. 
The -I and -i options are mutually-exclusive; the last one specified shall take 
effect. 
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41912 

41913 

41914 

41915 

41916 

41917 

41918 

41919 

41920 

41921 

41922 

41923 

41924 

41925 

41926 

41927 

41928 

41929 

41930 

41931 

41932 

41933 

41934 

41935 

41936 

41937 

41938 

41939 

41940 

41941 

41942 

41943 

41944 

41945 

41946 

41947 

41948 

41949 

41950 

41951 

41952 


xsi -L number The utility shall be executed for each non-empty number lines of arguments from 
standard input. The last invocation of utility shall be with fewer lines of arguments 
if fewer than number remain. A line is considered to end with the first <newline> 
character unless the last character of the line is a <blank> character; a trailing 
<blank> character signals continuation to the next non-empty line, inclusive. The 
-L, — 1, and -n options are mutually-exclusive; the last one specified shall take 
effect. 

-n number Invoke utility using as many standard input arguments as possible, up to number (a 
positive decimal integer) arguments maximum. Fewer arguments shall be used if: 

• The command line length accumulated exceeds the size specified by the -s 
option (or |LINE_MAX} if there is no -s option). 

• The last iteration has fewer than but not zero, operands remaining. 

man -p Prompt mode: the user is asked whether to execute utility at each invocation. Trace 

mode (-t) is turned on to write the command instance to be executed, followed by 
a prompt to standard error. An affirmative response read from /dev/tty shall 
execute the command; otherwise, that particular invocation of utility shall be 
skipped. 

Invoke utility using as many standard input arguments as possible yielding a 
command line length less than size (a positive decimal integer) bytes. Fewer 
arguments shall be used if: 

• The total number of arguments exceeds that specified by the -n option. 

• The total number of lines exceeds that specified by the -L option. 

• End-of-file is encountered on standard input before size bytes are accumulated. 

Values of size up to at least |LINE_MAX} bytes shall be supported, provided that 
the constraints specified in the DESCRIPTION are met. It shall not be considered 
an error if a value larger than that supported by the implementation or exceeding 
the constraints specified in the DESCRIPTION is given; xargs shall use the largest 
value it supports within the constraints. 

Enable trace mode. Each generated command line shall be written to standard 
error just prior to invocation. 

Terminate if a command line containing number arguments (see the -n option 
above) or number lines (see the -L option above) will not fit in the implied or 
specified size (see the -s option above). 


-s size 


xsi 


-t 

-x 

XSI 


OPERANDS 

The following operands shall be supported: 

utility The name of the utility to be invoked, found by search path using the PATH I 

environment variable, described in the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. If utility is omitted, the I 
default shall be the echo utility. If the utility operand names any of the special 
built-in utilities in Section 2.14 on page 96, the results are undefined. 

argument An initial option or operand for the invocation of utility. 
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41953 STDIN 

41954 The standard input shall be a text file. The results are unspecified if an end-of-file condition is I 

41955 detected immediately following an escaped <newline> character. 


41956 INPUT FILES 

41957 man The file /dev/tty is used to read responses required by the -p option. 


41958 ENVIRONMENT VARIABLES 

41959 The following environment variables shall affect the execution of xargs: 


41960 

41961 

41962 

41963 

41964 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


41965 

41966 


LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 


41967 

41968 

41969 

41970 


LC_COLLATE 

Determine the locale for the behavior of ranges, equivalence classes and multi¬ 
character collating elements used in the extended regular expression defined for 
the yesexpr locale keyword in the LC_MESSAGES category. 


41971 

41972 

41973 

41974 

41975 


LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files) and the behavior of character classes used in the 
extended regular expression defined for the yesexpr locale keyword in the 
LC_MESSAGES category. 


41976 LC_MESSAGES 

41977 Determine the locale for the processing of affirmative responses and that should be 

41978 used to affect the format and contents of diagnostic messages written to standard 

41979 error. 


41980 xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

41981 PATH Determine the location of utility, as described in the System Interface Definitions I 

41982 volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

41983 ASYNCHRONOUS EVENTS 

41984 Default. 


41985 STDOUT 

41986 Not used. 


41987 STDERR 

41988 MAN 

41989 

41990 MAN 

41991 


Used for diagnostic messages and the -t and -p options. If the -t option is specified, the utility 
and its constructed argument list shall be written to standard error, as it will be invoked, prior to 
invocation. If -p is specified, a prompt of the following format shall be written (in the POSIX 
locale): 


41992 


41993 


at the end of the line of the output from -t. 
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41994 OUTPUT FILES 

41995 None. 

41996 EXTENDED DESCRIPTION 

41997 None. 

41998 EXIT STATUS 

41999 The following exit values shall be returned: 

42000 0 All invocations of utility returned exit status zero. 

42001 1-125 A command line meeting the specified requirements could not be assembled, one or 

42002 more of the invocations of utility returned a non-zero exit status, or some other error 

42003 occurred. 

42004 1 26 The utility specified by utility was found but could not be invoked. 

42005 1 27 The utility specified by utility could not be found. 

42006 CONSEQUENCES OF ERRORS 

42007 If a command line meeting the specified requirements cannot be assembled, the utility cannot be 

42008 invoked, an invocation of the utility is terminated by a signal, or an invocation of the utility exits 

42009 with exit status 255, the xargs utility shall write a diagnostic message and exit without 

42010 processing any remaining input. 

42011 APPLICATION USAGE 

42012 The 255 exit status allows a utility being used by xargs to tell xargs to terminate if it knows no 

42013 further invocations using the current data stream succeeds. Thus, utility should explicitly exit 

42014 with an appropriate value to avoid accidentally returning with 255. 

42015 Note that input is parsed as lines; <blank> characters separate arguments. If xargs is used to 

42016 bundle output of commands like find dir -print or Is into commands to be executed, unexpected 

42017 results are likely if any file names contain any <blank> characters or <newline> characters. This 

42018 can be fixed by using find to call a script that converts each file found into a quoted string that is 

42019 then piped to xargs. Note that the quoting rules used by xargs are not the same as in the shell. 

42020 They were not made consistent here because existing applications depend on the current rules 

42021 and the shell syntax is not fully compatible with it. An easy rule that can be used to transform 

42022 any string into a quoted form that xargs interprets correctly is to precede each character in the 

42023 string with a backslash. 

42024 On implementations with a large value for {ARG_MAX}, xargs may produce command lines 

42025 longer than {LINE_MAX}. For invocation of utilities, this is not a problem. If xargs is being used 

42026 to create a text file, users should explicitly set the maximum command line length with the -s 

42027 option. 

42028 The command, env, nice, nohup, time, and xargs utilities have been specified to use exit code 127 if 

42029 an error occurs so that applications can distinguish "failure to find a utility" from "invoked 

42030 utility exited with an error indication". The value 127 was chosen because it is not commonly 

42031 used for other meanings; most utilities use small values for "normal error conditions" and the 

42032 values above 128 can be confused with termination due to receipt of a signal. The value 126 was 

42033 chosen in a similar manner to indicate that the utility could be found, but not invoked. Some 

42034 scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction 

42035 between exit codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to 

42036 exec the utility fail with [ENOENT], and uses 126 when any attempt to exec the utility fails for 

42037 any other reason. 
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EXAMPLES 

1. The following moves all files from directory $1 to directory $2, and echo each move 
command just before doing it: 

Is $1 | xargs —I {} —t mv $1/{ } $2 / { } 

2. The following command combines the output of the parenthesised commands onto one 
line, which is then written to the end-of-file log: 

(logname; date; printf "%s\n" "$0 $*") | xargs >>log 

3. The following command invokes diff with successive pairs of arguments originally typed 
as command line arguments (assuming there are no embedded <blank> characters in the 
elements of the original argument list): 

printf "%s\n" "$*" | xargs —n 2 —x diff 

4. The user is asked which files in the current directory shall be archived. The files are 
archived into arch; a, one at a time, or b, many at a time. 

a. is I xargs —p —L 1 ar —r arch 

b. is | xargs —p —L 1 | xargs ar —r arch 

5. The following executes with successive pairs of arguments originally typed as command 
line arguments: 

echo $* | xargs —n 2 diff 

RATIONALE 

The xargs utility was usually found only in System V-based systems; BSD systems included an 
apply utility that provided functionality similar to xargs -n number. The SVID lists xargs as a 
software development extension. This volume of IEEE Std. 1003.1-200x does not share the view 
that it is used only for development, and therefore it is not optional. 

The classic application of the xargs utility is in conjunction with the find utility to reduce the 
number of processes launched by a simplistic use of the find -exec combination. The xargs utility 
is also used to enforce an upper limit on memory required to launch a process. With this basis in 
mind, this volume of IEEE Std. 1003.1-200x selected only the minimal features required. 

The -n number option was used classically to evoke a utility using pairs of operands, yet the 
general case has problems when utility spawns child processes of its own. The xargs utility can 
sap resources from these children, especially those sharing the environment of the parent. 

The command, env, nolntp, and xargs utilities have been specified to use exit code 127 if an error 
occurs so that applications can distinguish "failure to find a utility" from "invoked utility exited 
with an error indication". The value 127 was chosen because it is not commonly used for other 
meanings; most utilities use small values for "normal error conditions", and the values above 
128 can be confused with termination due to receipt of a signal. The value 126 was chosen in a 
similar manner to indicate that the utility could be found, but not invoked. Some scripts produce 
meaningful error messages differentiating the 126 and 127 cases. The distinction between exit 
codes 126 and 127 is based on KomShell practice that uses 127 when all attempts to exec the 
utility fail with [ENOENT] and that uses 126 when any attempt to exec the utility fails for any 
other reason. 

Although the 255 exit status is mostly an accident of historical implementations, it allows a 
utility being used by xargs to tell xargs to terminate if it knows no further invocations using the 
current data stream shall succeed. Any non-zero exit status from a utility falls into the 1-125 
range when xargs exits. There is no statement of how the various non-zero utility exit status 
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42082 codes are accumulated by xargs. The value could be the addition of all codes, their highest 

42083 value, the last one received, or a single value such as 1. Since no algorithm is arguably better 

42084 than the others, and since many of the standard utilities say little more (portably) than 

42085 "pass/fail", no new algorithm was invented. 

42086 Several other xargs options were withdrawn because simple alternatives already exist within this 

42087 volume of IEEE Std. 1003.1-200x. For example, the -e eofstr option can be replaced by features of 

42088 sed. The -i replstr option can be just as efficiently performed using a shell for loop. Since xargs 

42089 calls an exec function with each input line, the -i option does not usually exploit the grouping 

42090 capabilities of xargs. 

42091 The requirement that xargs never produce command lines such that invocation of utility is 

42092 within 2 048 bytes of hitting the POSIX exec j ARG_MAX} limitations is intended to guarantee 

42093 that the invoked utility has room to modify its environment variables and command line I 

42094 arguments and still be able to invoke another utility. Note that the minimum {ARG_MAX} I 

42095 allowed by the System Interfaces volume of IEEE Std. 1003.l-200x is 4096 bytes and the 

42096 minimum value allowed by the this volume of IEEE Std. 1003.1-200x is 2 048 bytes; therefore, the 

42097 2 048 bytes difference seems reasonable. Note, however, that xargs may never be able to invoke a 

42098 utility if the environment passed in to xargs comes close to using {ARG_MAX} bytes. 

42099 The version of xargs required by this volume of IEEE Std. 1003.1-200x is required to wait for the 

42100 completion of the invoked command before invoking another command. This was done because 

42101 historical scripts using xargs assumed sequential execution. Implementations wanting to provide 

42102 parallel operation of the invoked utilities are encouraged to add an option enabling parallel 

42103 invocation, but should still wait for termination of all of the children before xargs terminates 

42104 normally. I 

42105 The -e option was omitted from the ISO POSIX-2:1993 standard in the belief that the eofstr I 

42106 option-argument was recognized only when it was on a line by itself and before quote and I 

42107 escape processing were performed, and that the logical end-of-file processing was only enabled I 

42108 if a -e option was specified. In that case, a simple sed script could be used to duplicate the -e I 

42109 functionality. Further investigation revealed that: I 

42110 • The logical end-of-file string was checked for after quote and escape processing, making a sed I 

42111 script that provided equivalent functionality much more difficult to write. I 

42112 • The default was to perform logical end-of-file processing with an underscore as the logical I 

42113 end-of-file string. I 

42114 To correct this misunderstanding, the -E eofstr option was adopted from Issue 4 in an I 

42115 amendment to IEEE Std. 1003.1-200x. Users should note that the description of the -E option I 

42116 matches historical documentation of the -e option (which was not adopted because it did not I 

42117 support the Utility Syntax Guidelines), by saying that if eofstr is the null string, logical end-of-file I 

42118 processing is disabled. Historical implementations of xargs actually did not disable logical end- I 

42119 of-file processing; they treated a null argument found in the input as a logical end-of-file string. I 

42120 (A null string argument could be generated using single or double quotes (' ' or""). Since this I 

42121 behavior was not documented historically, it is considered to be a bug. I 

42122 FUTURE DIRECTIONS 

42123 A version supporting the Utility Syntax Guidelines may be introduced. I 

42124 SEE ALSO 

42125 echo 
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42126 

42127 

42128 

42129 

42130 

42131 

42132 

42133 

42134 

42135 

42136 

42137 

42138 

42139 

42140 

42141 


CHANGE HISTORY 

First released in Issue 2. 

Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

Second FUTURE DIRECTION added. 

Issue 6 

The obsolescent -e, -i, and -1 options are removed. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The -p option is added. 

• In the INPUT FILES section, the file /dev/tty is used to read responses required by the -p 
option. 

• The STDERR section is updated to describe the -p option. 

The description of the -E option is aligned with the ISO POSIX-2:1993 standard. 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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42142 NAME 

42143 yacc — yet another compiler compiler (DEVELOPMENT) 

42144 SYNOPSIS 

42145 yacc [—dltv] [—b file_prefix ] [—p sym_prefix ] grammar 


42146 DESCRIPTION 

42147 The yacc utility shall read a description of a context-free grammar in file and write C source code, 

42148 conforming to the ISO C standard, to a code file, and optionally header information into a 

42149 header file, in the current directory. The C code shall define a function and related routines and 

42150 macros for an automaton that executes a parsing algorithm meeting the requirements in 

42151 Algorithms on page 1119. 

42152 The form and meaning of the grammar are described in the EXTENDED DESCRIPTION section. 

42153 The C source code and header file shall be produced in a form suitable as input for the C 

42154 compiler (see c89 on page 246). 


42155 OPTIONS 

42156 The yacc utility shall conform to the System Interface Definitions volume of I 

42157 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. I 


42158 The following options shall be supported: 


42159 

42160 

42161 

42162 


-b filepprefix Use file_prefix instead of y as the prefix for all output file names. The code file 
y.tab.c, the header file y.tab.h (created when -d is specified), and the description 
file y.output (created when -v is specified), shall be changed to filepprefix.tab.c, 
filepprefix .tab.h, and filepprefix .output, respectively. 


42163 -d 

42164 

42165 


Write the header file; by default only the code file is written. The #define 
statements that associate the token codes assigned by yacc with the user-declared 
token names. This allows source files other than y.tab.c to access the token codes. 


42166 -1 

42167 

42168 

42169 


Produce a code file that does not contain any Mine constructs. If this option is not 
present, it is unspecified whether the code file or header file contains Mine 
directives. This should only be used after the grammar and the associated actions 
are fully debugged. 


42170 

42171 

42172 

42173 

42174 

42175 


-p sympprefix Use sympprefix instead of yy as the prefix for all external names produced by yacc. 

The names affected shall include the functions yyparse, yylex, and yyerror, and the 
variables yylval, yyclmr, and yydebug. (In the remainder of this section, the six 
symbols cited are referenced using their default names only as a notational 
convenience.) Local names may also be affected by the -p option; however, the -p 
option shall not affect #define symbols generated by yacc. 


42176 -t 

42177 

42178 

42179 


Modify conditional compilation directives to permit compilation of debugging I 
code in the code file. Runtime debugging statements shall always be contained in I 
the code file, but by default conditional compilation directives prevent their 
compilation. 


42180 -v Write a file containing a description of the parser and a report of conflicts 

42181 generated by ambiguities in the grammar. 


42182 OPERANDS 

42183 The following operand is required: 


42184 

42185 

42186 


grammar A path name of a file containing instructions, hereafter called grammar , for which a 
parser is to be created. The format for the grammar is described in the EXTENDED 
DESCRIPTION section. 
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42187 

42188 

42189 

42190 

42191 

42192 

42193 

42194 

42195 

42196 

42197 

42198 

42199 

42200 

42201 

42202 

42203 

42204 

42205 

42206 

42207 

42208 

42209 

42210 

42211 

42212 

42213 

42214 

42215 

42216 

42217 

42218 

42219 

42220 

42221 

42222 

42223 


STDIN 

Not used. 

INPUT FILES 

The file grammar shall be a text file formatted as specified in the EXTENDED DESCRIPTION I 
section. 

ENVIRONMENT VARIABLES 

The following environment variables shall affect the execution of yacc: 

LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 

LC_ALL If set to a non-empty string value, override the values of all the other 
internationalization variables. 

LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments and input files). 

LC_MESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 

xsi NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 

The LANG and LC_* variables affect the execution of the yacc utility as stated. The main function 
defined in Yacc Library on page 1119 shall call: 

setlocale(LC_ALL, "") 

and thus, the program generated by yacc also shall be affected by the contents of these variables 
at runtime. 

ASYNCHRONOUS EVENTS 
Default. 

STDOUT 

Not used. 

STDERR 

If shift/reduce or reduce/reduce conflicts are detected in grammar, yacc writes a report of those 
conflicts to the standard error in an unspecified format. 

Standard error is also used for diagnostic messages. 

OUTPUT FILES 

The code file, the header file, and the description file shall be text files. All are described in the 
following sections. 
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42261 

42262 

42263 

42264 


yacc 


Utilities 


Code File 

This file shall contain the C source code for the yyparse routine. It shall contain code for the 
various semantic actions with macro substitution performed on them as described in the 
EXTENDED DESCRIPTION section. It also shall contain a copy of the #define statements in the 
header file. If a %union declaration is used, the declaration for YYSTYPE shall be also included 
in this file. I 

Header File I 

The header file shall contain #define statements that associate the token numbers with the token I 
names. This allows source files other than the code file to access the token codes. If a %union 
declaration is used, the declaration for YYSTYPE and an extern YYSTYPE yylval declaration shall 
be also included in this file. I 

Description File I 

The description file shall be a text file containing a description of the state machine I 
corresponding to the parser, using an unspecified format. Limits for internal tables (see Limits 
on page 1120) shall also be reported, in an implementation-dependent manner. (Some 
implementations may use dynamic allocation techniques and have no specific limit values to 
report.) 

EXTENDED DESCRIPTION 

The yacc command accepts a language that is used to define a grammar for a target language to 
be parsed by the tables and code generated by yacc. The language accepted by yacc as a 
grammar for the target language is described below using the yacc input language itself. 

The input grammar includes rules describing the input structure of the target language and code 
to be invoked when these rules are recognized to provide the associated semantic action. The 
code to be executed shall appear as bodies of text that are intended to be C-language code. The 
C-language inclusions are presumed to form a correct function when processed by yacc into its 
output files. The code included in this way shall be executed during the recognition of the target 
language. 

Given a grammar, the yacc utility generates the files described in the OUTPUT FILES section. 
The code file can be compiled and linked using cc or c89. If the declaration and programs 
sections of the grammar file did not include definitions of main, yylex, and yyerror , the compiled 
output requires linking with externally supplied version of those functions. Default versions of 
main and yyerror are supplied in the yacc library and can be linked in by using the -1 y operand to 
c89. The yacc library interfaces need not support interfaces with other than the default yy 
symbol prefix. The application provides the lexical analyzer function, yylex ; the lex utility is 
specifically designed to generate such a routine. 

Input Language 

The application ensure that every specification file consists of three sections in order: I 
declarations, grammar rules, and programs, separated by double percent signs ("%%"). The 
declarations and programs sections can be empty. If the latter is empty, the preceding "%%" 
mark separating it from the rules section can be omitted. 

The input is free form text following the structure of the grammar defined below. 
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42302 

42303 

42304 

42305 

42306 

42307 

42308 

42309 


Lexical Structure of the Grammar 

The characters <blank>, <newline>, and <form-feed> shall be ignored, except that the I 
application shall ensure that they do not appear in names or multi-character reserved symbols. I 
Comments shall be enclosed in " / * ... * / ", and can appear wherever a name is valid. I 

Names are of arbitrary length, made up of letters, periods (' .'), underscores and non¬ 

initial digits. Uppercase and lowercase letters are distinct. Portable applications shall not use I 
names beginning in yy or YY since the yacc parser uses such names. Many of the names appear I 
in the final output of yacc, and thus they should be chosen to conform with any additional rules 
created by the C compiler to be used. In particular they appear in #define statements. 

A literal shall consist of a single character enclosed in single-quotes (' ''). All of the escape 
sequences supported for character constants by the ISO C standard shall be supported by yacc. 

The relationship with the lexical analyzer is discussed in detail below. 

The application shall ensure that the NUL character is not used in grammar rules or literals. I 

Declarations Section 

The declarations section is used to define the symbols used to define the target language and 
their relationship with each other. In particular, much of the additional information required to 
resolve ambiguities in the context-free grammar for the target language is provided here. 

Usually yacc assigns the relationship between the symbolic names it generates and their 
underlying numeric value. The declarations section makes it possible to control the assignment 
of these values. 

It is also possible to keep semantic information associated with the tokens currently on the parse 
stack in a user-defined C-language union, if the members of the union are associated with the 
various names in the grammar. The declarations section provides for this as well. 

The first group of declarators below all take a list of names as arguments. That list can optionally 
be preceded by the name of a C union member (called a tag below) appearing within ' <' and 
' . (As an exception to the typographical conventions of the rest of this volume of 

IEEE Std. 1003.1-200x, in this case <tag> does not represent a metavariable, but the literal angle 
bracket characters surrounding a symbol.) The use of tag specifies that the tokens named on this I 
line shall be of the same C type as the union member referenced by tag. This is discussed in I 
more detail below. 

For lists used to define tokens, the first appearance of a given token can be followed by a 
positive integer (as a string of decimal digits). If this is done, the underlying value assigned to it 
for lexical purposes is taken to be that number. 

%token [<tag>] name [number][name [number]]... 

Declares names to be a token. If tag is present, the C type for all tokens on this line shall be 
declared to be the type referenced by tag. If a positive integer, number, follows a name, that 
value shall be assigned to the token. 

%left [<tag>] name [number][name [number]]... 

%right [<tag>] name [number][name [number]]... 

Declares name to be a token, and assigns precedence to it. One or more lines, each beginning 
with one of these symbols, can appear in this section. All tokens on the same line have the 
same precedence level and associativity; the lines are in order of increasing precedence or 
binding strength. %left denotes that the operators on that line are left associative, and 
%right similarly denotes right associative operators. If tag is present, it shall declare a C 
type for names as described for %token. 
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42322 

42323 

42324 

42325 
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42335 
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42337 
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42339 

42340 
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42343 

42344 

42345 

42346 

42347 

42348 

42349 

42350 

42351 

42352 

42353 

42354 


%nonassoc [<tag>] name [number][name [number]]... 

Declares name to be a token, and indicates that this cannot be used associatively. If the 
parser encounters associative use of this token it reports an error. If tag is present, it shall 
declare a C type for names as described for %token. 

%type [<tag>] name... 

Declares that union member names are non-terminals, and thus it is required to have a tag 
field at its beginning. Because it deals with non-terminals only, assigning a token number or 
using a literal is also prohibited. If this construct is present, yacc shall perform type 
checking; if this construct is not present, the parse stack shall hold only the int type. 

Every name used in grammar undefined by a %token, %left, %right, or %nonassoc declaration is 
assumed to represent a non-terminal symbol. The yacc utility shall report an error for any non¬ 
terminal symbol that does not appear on the left side of at least one grammar rule. 

Once the type, precedence, or token number of a name is specified, it shall not be changed. If the 
first declaration of a token does not assign a token number, yacc shall assign a token number. 
Once this assignment is made, the token number shall not be changed by explicit assignment. 

The following declarators do not follow the previous pattern. 

%start name 

Declares the non-terminal name to be the start symbol, which represents the largest, most 
general structure described by the grammar rules. By default, it is the left-hand side of the 
first grammar rule; this default can be overridden with this declaration. 

%union { body of union (in C)} 

Declares the yacc value stack to be a union of the various types of values desired. By default, 
the values returned by actions (see below) and the lexical analyzer shall be integers. The 
yacc utility keeps track of types, and it shall insert corresponding union member names in 
order to perform strict type checking of the resulting parser. 

Alternatively, given that at least one <tag> construct is used, the union can be declared in a 
header file (which shall be included in the declarations section by using an #include 
construct within %{ and %}), and a typedef used to define the symbol YYSTYPE to 
represent this union. The effect of %union is to provide the declaration of YYSTYPE directly 
from the yacc input. 

%{...%} 

C-language declarations and definitions can appear in the declarations section, enclosed by 
these marks. These statements shall be copied into the code file, and have global scope 
within it so that they can be used in the rules and program sections. 

The application shall ensure that the declarations section is terminated by the token %%. 

Grammar Rules in yacc 

The rules section defines the context-free grammar to be accepted by the function yacc generates, 
and associates with those rules C-language actions and additional precedence information. The 
grammar is described below, and a formal definition follows. 

The rules section is comprised of one or more grammar rules. A grammar rule has the form: 

A : BODY ; 

The symbol A represents a non-terminal name, and BODY represents a sequence of zero or 
more name s, literals, and semantic actions that can then be followed by optional precedence rules. 
Only the names and literals participate in the formation of the grammar; the semantic actions 
and precedence rules are used in other ways. The colon and the semicolon are yacc punctuation. 
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If there are several successive grammar rules with the same left-hand side, the vertical bar ' | ' 
can be used to avoid rewriting the left-hand side; in this case the semicolon appears only after 
the last rule. The BODY part can be empty (or empty of names and literals) to indicate that the 
non-terminal symbol matches the empty string. 

The yacc utility assigns a unique number to each rule. Rules using the vertical bar notation are 
distinct rules. The number assigned to the rule appears in the description file. 

The elements comprising a BODY are: 

name, literal 

These form the rules of the grammar: name is either a token or a non-terminal ; literal 
stands for itself (less the lexically required quotation marks). 

semantic action 

With each grammar rule, the user can associate actions to be performed each time 
the rule is recognized in the input process. (Note that the word "action" can also 
refer to the actions of the parser—shift, reduce, and so on.) 

These actions can return values and can obtain the values returned by previous 
actions. These values are kept in objects of type YYSTYPE (see %union). The 
result value of the action shall be kept on the parse stack with the left-hand side of 
the rule, to be accessed by other reductions as part of their right-hand side. By 
using the <tag> information provided in the declarations section, the code 
generated by yacc can be strictly type checked and contain arbitrary information. In 
addition, the lexical analyzer can provide the same kinds of values for tokens, if 
desired. 

An action is an arbitrary C statement and as such can do input or output, call 
subprograms and alter external variables. An action is one or more C statements 
enclosed in curly braces ' {' and ' }' • 

Certain pseudo-variables can be used in the action. These are macros for access to 
data structures known internally to yacc. 

$$ The value of the action can be set by assigning it to $$. If type 

checking is enabled and the type of the value to be assigned cannot 
be determined, a diagnostic message may be generated. 

$number This refers to the value returned by the component specified by the 

token number in the right side of a rule, reading from left to right; 
number can be zero or negative. If it is, it refers to the data associated 
with the name on the parser's stack preceding the leftmost symbol of 
the current rule. (That is, "$0" refers to the name immediately 
preceding the leftmost name in the current rule, to be found on the 
parser's stack and " $-1" refers to the symbol to its left.) If number 
refers to an element past the current point in the rule, or beyond the 
bottom of the stack, the result is undefined. If type checking is 
enabled and the type of the value to be assigned cannot be 
determined, a diagnostic message may be generated. 

$<tag>nnmber 

These correspond exactly to the corresponding symbols without the 
tag inclusion, but allow for strict type checking (and preclude 
unwanted type conversions). The effect is that the macro is expanded 
to use tag to select an element from the YYSTYPE union (using 
dataname.tag). This is particularly useful if number is not positive. 
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$<tag>$ This imposes on the reference the type of the union member 
referenced by tag. This construction is applicable when a reference 
to a left context value occurs in the grammar, and provides yacc with 
a means for selecting a type. 

Actions can occur in the middle of a rule as well as at the end; an action can access 
values returned by actions to its left, and in turn the value it returns can be 
accessed by actions to its right. An action appearing in the middle of a rule shall be 
equivalent to replacing the action with a new non-terminal symbol and adding an 
empty rule with that non-terminal symbol on the left-hand side. The semantic 
action associated with the new rule shall be equivalent to the original action. The 
use of actions within rules might introduce conflicts that would not otherwise 
exist. 

By default, the value of a rule shall be the value of the first element in it. If the first 
element does not have a type (particularly in the case of a literal) and type 
checking is turned on by %type an error message shall result. 

precedence The keyword %prec can be used to change the precedence level associated with a 
particular grammar rule. Examples of this are in cases where a unary and binary 
operator have the same symbolic representation, but need to be given different 
precedences, or where the handling of an ambiguous if-else construction is 
necessary. The reserved symbol %prec can appear immediately after the body of 
the grammar rule and can be followed by a token name or a literal. It shall cause 
the precedence of the grammar rule to become that of the following token name or 
literal. The action for the rule as a whole can follow %prec. 

If a program section follows, the application shall ensure that the grammar rules are terminated I 
by %%. I 

Programs Section 

The programs section can include the definition of the lexical analyzer yylex(), and any other I 
functions, for example those used in the actions specified in the grammar rules. It is unspecified I 
whether the programs section precedes or follows the semantic actions in the output file; I 
therefore, if the application contains any macro definitions and declarations intended to apply to I 
the code in the semantic actions, it shall place them within " % { ... % } " in the declarations I 
section. 

Input Grammar 

The following input to yacc yields a parser for the input to yacc. This formal syntax takes 
precedence over the preceding text syntax description. 

The lexical structure is defined less precisely; Lexical Structure of the Grammar on page till 
defines most terms. The correspondence between the previous terms and the tokens below is as 
follows. 

IDENTIFIER This corresponds to the concept of name, given previously. It also includes 
literals as defined previously. 

C_IDENTIFIER This is a name, and additionally it is known to be followed by a colon. A literal 
cannot yield this token. 

NUMBER A string of digits (a non-negative decimal integer). 

TYPE, LEFT, MARK, and so on 

These correspond directly to %type, %left, %%, and so on. 
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42447 {...} This indicates C-language source code, with the possible inclusion of ' $' 

42448 macros as discussed previously. 


42449 Notes to Reviewers 

42450 This section ivith side shading will not appear in the final copy. - Ed. 

42451 Dl, XCU, ERN 375 says that}% should be replaced by %} for RCURL below, but the text is as per 

42452 existing .2. Comments? 

42453 /* Grammar for the input to yacc. */ 

42454 /* Basic entries. */ 

42455 /* The following are recognized by the lexical analyzer. */ 

42456 %token IDENTIFIER /* Includes identifiers and literals */ 

42457 %token C_IDENTIFIER /* identifier (but not literal) 

42458 followed by a : . */ 

42459 %token NUMBER /* [0-9] [0-9]* */ 

42460 /* Reserved words : %type=>TYPE %left=>LEFT, and so on */ 

42461 %token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION 


42462 

%token 

MARK 

/* 

The 

%% mark. 

*/ 

42463 

%token 

LCURL 

/* 

The 

%{ mark. 

*/ 

42464 

%token 

RCURL 

/* 

The 

}% mark. 

*/ 


42465 /* 8-bit character literals stand for themselves; */ 

42466 /* tokens have to be defined for multi-byte characters. */ 

42467 %start spec 

42468 %% 


42469 

42470 

42471 

42472 

42473 

42474 

42475 

42476 

42477 

42478 

42479 

42480 

42481 

42482 

42483 

42484 

42485 

42486 

42487 

42488 

42489 

42490 

42491 

42492 


spec : defs MARK rules tail 

r 

tail : MARK 

{ 

/* In this action, set up the rest of the file. */ 

} 

| /* Empty; the second MARK is optional. */ 

r 

defs : /* Empty. */ 

I defs def 

r 

def : START IDENTIFIER 
I UNION 

{ 

/* Copy union definition to output. */ 

} 

| LCURL 

{ 

/* Copy C code to output file. */ 

} 

RCURL 

| rword tag nlist 

I 

rword : TOKEN 
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1 

LEFT 

42494 

1 

RIGHT 

42495 

1 

NONASSOC 

42496 

1 

TYPE 

42497 

r 


42498 

tag : 

/* Empty: union tag ID optional. */ 

42499 

1 

'<’ IDENTIFIER '>' 

42500 

r 


42501 

nlist : 

nmno 

42502 

1 

nlist nmno 

42503 

r 


42504 

nmno : 

IDENTIFIER /* Note: literal invalid with % type. */ 

42505 

i 

IDENTIFIER NUMBER /* Note: invalid with % type. */ 

42506 

r 


42507 

/* Rule 

section */ 

42508 

rules : 

C_IDENTIFIER rbody prec 

42509 

! 

rules rule 

42510 

r 


42511 

rule : 

C_IDENTIFIER rbody prec 

42512 

1 

'|' rbody prec 

42513 

r 


42514 

rbody : 

/* empty */ 

42515 

1 

rbody IDENTIFIER 

42516 

1 

rbody act 

42517 

r 


42518 

act : 

' {' 

42519 


{ 

42520 


/* Copy action, translate $$, and so on. */ 

42521 


} 

42522 


' }' 

42523 

r 


42524 

prec : 

/* Empty */ 

42525 

i 

PREC IDENTIFIER 

42526 

i 

PREC IDENTIFIER act 

42527 

i 

prec ';' 

42528 

i 


42529 

Conflicts 


42530 

The parser produced for an input grammar may contain states in which conflicts occur. The 

42531 

conflicts occur because the grammar is not LALR(l). An ambiguous grammar always contains at 

42532 

least one LALR(l) conflict. The yacc utility shall resolve all conflicts, using either default rules or 

42533 

user-specified precedence rules. 

42534 

Conflicts are either shift/reduce conflicts or reduce/reduce conflicts. A shift/reduce conflict is 

42535 

where, for a given state and lookahead symbol, both a shift action and a reduce action are 

42536 

possible. A reduce/reduce conflict is where, for a given state and lookahead symbol, reductions 

42537 

by two different rules are possible. 

42538 

The rules below describe how to specify what actions to take when a conflict occurs. Not all 

42539 

shift/reduce conflicts can be successfully resolved this way because the conflict may be due to 

42540 

something other than ambiguity, so incautious use of these facilities can cause the language 
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accepted by the parser to be much different from that which was intended. The description file 
shall contain sufficient information to understand the cause of the conflict. Where ambiguity is 
the reason either the default or explicit rules should be adequate to produce a working parser. 

The declared precedences and associativities (see Declarations Section on page till) are used 
to resolve parsing conflicts as follows: 

1. A precedence and associativity is associated with each grammar rule; it is the precedence 
and associativity of the last token or literal in the body of the rule. If the %prec keyword is 
used, it overrides this default. Some grammar rules might not have both precedence and 
associativity. 

2. If there is a shift /reduce conflict, and both the grammar rule and the input symbol have 
precedence and associativity associated with them, then the conflict is resolved in favor of 
the action (shift or reduce) associated with the higher precedence. If the precedences are 
the same, then the associativity is used; left associative implies reduce, right associative 
implies shift, and non-associative implies an error in the string being parsed. 

3. When there is a shift/reduce conflict that cannot be resolved by rule 2, the shift is done. 
Conflicts resolved this way are counted in the diagnostic output described in Error 
Handling. 

4. When there is a reduce/reduce conflict, a reduction is done by the grammar rule that 
occurs earlier in the input sequence. Conflicts resolved this way are counted in the 
diagnostic output described in Error Handling. 

Conflicts resolved by precedence or associativity shall not be counted in the shift/reduce and 
reduce/reduce conflicts reported by yacc on either standard error or in the description file. 

Error Handling 

The token error shall be reserved for error handling. The name error can be used in grammar 
rules. It indicates places where the parser can recover from a syntax error. The default value of 
error shall be 256. Its value can be changed using a %token declaration. The lexical analyzer 
should not return the value of error. (Multi-byte characters should be recognized by the lexical 
analyzer and returned as tokens. They should not be returned as multi-byte character literals. 
The token error that is used for error recovery is normally assigned the value 256 in the historical 
implementation. Thus, the token value 256, which used in many multi-byte character sets, is not 
available for use as the value of a user-defined token.) 

The parser shall detect a syntax error when it is in a state where the action associated with the 
lookahead symbol is error. A semantic action can cause the parser to initiate error handling by 
executing the macro YYERROR. When YYERROR is executed, the semantic action passes 
control back to the parser. YYERROR cannot be used outside of semantic actions. 

When the parser detects a syntax error, it normally calls yyerror with the character string 
"syntax error" as its argument. The call shall not be made if the parser is still recovering 
from a previous error when the error is detected. The parser is considered to be recovering from 
a previous error until the parser has shifted over at least three normal input symbols since the 
last error was detected or a semantic action has executed the macro yyerrok. The parser shall not 
call yyerror when YYERROR is executed. 

The macro function YYRECOVERING shall return 1 if a syntax error has been detected and the 
parser has not yet fully recovered from it. Otherwise, zero shall be returned. 

When a syntax error is detected by the parser, the parser shall check if a previous syntax error 
has been detected. If a previous error was detected, and if no normal input symbols have been 
shifted since the preceding error was detected, the parser checks if the lookahead symbol is an 
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endmarker (see Interface to the Lexical Analyzer). If it is, the parser shall return with a non¬ 
zero value. Otherwise, the lookahead symbol shall be discarded and normal parsing shall 
resume. 

When YYERROR is executed or when the parser detects a syntax error and no previous error has 
been detected, or at least one normal input symbol has been shifted since the previous error was 
detected, the parser shall pop back one state at a time until the parse stack is empty or the 
current state allows a shift over error. If the parser empties the parse stack, it shall return with a 
non-zero value. Otherwise, it shall shift over error and then resume normal parsing. If the parser 
reads a lookahead symbol before the error was detected, that symbol shall still be the lookahead 
symbol when parsing is resumed. 

The macro yyerrok in a semantic action shall cause the parser to act as if it has fully recovered 
from any previous errors. The macro yyclearin shall cause the parser to discard the current 
lookahead token. If the current lookahead token has not yet been read, yyclearin shall have no 
effect. 

The macro YYACCEPT shall cause the parser to return with the value zero. The macro 
YYABORT shall cause the parser to return with a non-zero value. 

Interface to the Lexical Analyzer 

The yylex function is an integer-valued function that returns a token number representing the kind 
of token read. If there is a value associated with the token returned by yylex (see the discussion 
of tag above), it shall be assigned to the external variable yylval. 

If the parser and yylex do not agree on these token numbers, reliable communication between 
them cannot occur. For (one character) literals, the token is simply the numeric value of the 
character in the current character set. The numbers for other tokens can either be chosen by yacc, 
or chosen by the user. In either case, the #define construct of C is used to allow yylex to return 
these numbers symbolically. The #define statements are put into the code file, and the header 
file if that file is requested. The set of characters permitted by yacc in an identifier is larger than 
that permitted by C. Token names found to contain such characters shall not be included in the 
#define declarations. 

If the token numbers are chosen by yacc, the tokens other than literals shall be assigned numbers 
greater than 256, although no order is implied. A token can be explicitly assigned a number by 
following its first appearance in the declarations section with a number. Names and literals not 
defined this way retain their default definition. All token numbers assigned by yacc shall be 
unique and distinct from the token numbers used for literals and user-assigned tokens. If 
duplicate token numbers cause conflicts in parser generation, yacc shall report an error; 
otherwise, it is unspecified whether the token assignment is accepted or an error is reported. 

The end of the input is marked by a special token called the endmarker, which has a token 
number that is zero or negative. (These values are invalid for any other token.) All lexical 
analyzers shall return zero or negative as a token number upon reaching the end of their input. If 
the tokens up to, but excluding, the endmarker form a structure that matches the start symbol, 
the parser shall accept the input. If the endmarker is seen in any other context, it shall be 
considered an error. 
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Completing the Program 

In addition to yyparse and yylex, the functions yyerror and main are required to make a complete 
program. The application can supply main and yyerror, or those routines can be obtained from 
the yacc library. 

Yacc Library 

The following functions appear only in the yacc library accessible through the -1 y operand to cc 
or c89; they can therefore be redefined by a portable application: 

int main{\ oid) 

This function shall call yyparse and exit with an unspecified value. Other actions within this 
function are unspecified. 

int yyerror( const char *s) 

This function shall write the NUL-terminated argument to standard error, followed by a 
<newline> character. 

The order of the -1 y and -11 operands given to cc or c89 is significant; the application shall I 
either provide its own main function or ensure that -1 y precedes -11. I 

Debugging the Parser 

The parser generated by yacc shall have diagnostic facilities in it that can be optionally enabled I 
at either compile time or at runtime (if enabled at compile time). The compilation of the runtime I 
debugging code is under the control of YYDEBUG, a preprocessor symbol. If YYDEBUG has a 
non-zero value, the debugging code shall be included. If its value is zero, the code shall not be 
included. 

In parsers where the debugging code has been included, the external int yydebng can be used to 
turn debugging on (with a non-zero value) and off (zero value) at runtime. The initial value of I 
yydebng shall be zero. 

When -t is specified, the code file shall be built such that, if YYDEBUG is not already defined at 
compilation time (using the c89 -D YYDEBUG option, for example), YYDEBUG shall be set 
explicitly to 1. When -t is not specified, the code file shall be built such that, if YYDEBUG is not 
already defined, it shall be set explicitly to zero. 

The format of the debugging output is unspecified but includes at least enough information to 
determine the shift and reduce actions, and the input symbols. It also provides information 
about error recovery. 

Algorithms 

The parser constructed by yacc implements an LALR(l) parsing algorithm as documented in the 
literature. It is unspecified whether the parser is table-driven or direct-coded. 

A parser generated by yacc shall never request an input symbol from yylex while in a state where 
the only actions other than the error action are reductions by a single rule. 

The literature of parsing theory defines these concepts. 
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42665 Limits 

42666 The yacc utility may have several internal tables. The minimum maximums for these tables are 

42667 shown in the following table. The exact meaning of these values is implementation-dependent. 

42668 The implementation shall define the relationship between these values and between them and 

42669 any error messages that the implementation may generate should it run out of space for any 

42670 internal structure. An implementation may combine groups of these resources into a single pool 

42671 as long as the total available to the user does not fall below the sum of the sizes specified by this 

42672 section. 


42673 Table 4-22 Internal Limits in yacc 


42674 

42675 

Limit 

Minimum 

Maximum 

Description 

42676 

INTERMS} 

126 

Number of tokens. 

42677 

INNONTERM} 

200 

Number of non-terminals. 

42678 

INPROD} 

300 

Number of rules. 

42679 

INSTATES} 

600 

Number of states. 

42680 

IMEMSIZE} 

5200 

Length of rules. The total length, in names 

42681 



(tokens and non-terminals), of all the rules of the 

42682 



grammar. The left-hand side is counted for each 

42683 



rule, even if it is not explicitly repeated, as 

42684 



specified in Grammar Rules in yacc on page 

42685 



1112. 

42686 

jACTSIZE} 

4000 

Number of actions. "Actions" here (and in the 

42687 



description file) refer to parser actions (shift. 

42688 



reduce, and so on) not to semantic actions 

42689 



defined in Grammar Rules in yacc on page 1112. 


42690 EXIT STATUS 

42691 The following exit values shall be returned: 


42692 0 Successful completion. 

42693 >0 An error occurred. 

42694 CONSEQUENCES OF ERRORS 

42695 If any errors are encountered, the run is aborted and yacc exits with a non-zero status. Partial 

42696 code files and header files files may be produced. The summary information in the description 

42697 file always shall be produced if the -v flag is present. 

42698 APPLICATION USAGE 

42699 Historical implementations experience name conflicts on the names yacc.tmp, yacc.acts, 

42700 yacc.debug, y.tab.c, y.tab.h, and y.output if more than one copy of yacc is running in a single 

42701 directory at one time. The -b option was added to overcome this problem. The related problem 

42702 of allowing multiple yacc parsers to be placed in the same file was addressed by adding a -p 

42703 option to override the previously hard-coded yy variable prefix. 

42704 The description of the -p option specifies the minimal set of function and variable names that 

42705 cause conflict when multiple parsers are linked together. YYSTYPE does not need to be changed. 

42706 Instead, the programmer can use -b to give the header files for different parsers different names, 

42707 and then the file with the yylex for a given parser can include the header for that parser. Names 

42708 such as yyclearerr do not need to be changed because they are used only in the actions; they do 

42709 not have linkage. It is possible that an implementation has other names, either internal ones for 

42710 implementing things such as yyclearerr, or providing non-standard features that it wants to 

42711 change with -p. 
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42712 Unary operators that are the same token as a binary operator in general need their precedence 

42713 adjusted. This is handled by the %prec advisory symbol associated with the particular grammar 

42714 rule defining that unary operator. (See Grammar Rules in yacc on page 1112.) Applications are 

42715 not required to use this operator for unary operators, but the grammars that do not require it are 

42716 rare. 

42717 EXAMPLES 

42718 Access to the yacc library is obtained with library search operands to cc or c89. To use the yacc 

42719 library main : 

42720 c8 9 y.tab.c -1 y 

42721 Both the lex library and the yacc library contain main . To access the yacc main : 

42722 c8 9 y.tab.c lex.yy.c -1 y -1 1 

42723 This ensures that the yacc library is searched first, so that its main is used. 

42724 The historical yacc libraries have contained two simple functions that are normally coded by the 

42725 application programmer. These library functions are similar to the following code: 

42726 #include <locale.h> 

42727 int main (void) 

42728 { 

42729 extern int yyparseO; 

42730 setlocale (LC_ALL, 

42731 /* If the following parser is one created by lex, the 

42732 application must be careful to ensure that LC_CTYPE 

42733 and LC_COLLATE are set to the POSIX locale. */ 

42734 (void) yyparseO; 

42735 return (0); 

42736 } 

42737 #include <stdio.h> 

42738 int yyerror (const char *msg) 

42739 { 

42740 (void) fprintf (stderr, "%s\n", msg) ; 

42741 return (0); 

42742 } 

42743 RATIONALE 

42744 The references in Referenced Documents on page xv may be helpful in constructing the parser 

42745 generator. The referenced DeRemer, Frank, and Pennello Article (along with the works it 

42746 references) describes a technique to generate parsers that conform to this volume of 

42747 IEEE Std. 1003.1-200x. Work in this area continues to be done, so implementors should consult 

42748 current literature before doing any new implementations. The original Knuth Article is the 

42749 theoretical basis for this kind of parser, but the tables it generates are impractically large for 

42750 reasonable grammars and should not be used. The "equivalent to" wording is intentional to 

42751 assure that the best tables that are LALR(l) can be generated. 

42752 There has been confusion between the class of grammars, the algorithms needed to generate 

42753 parsers, and the algorithms needed to parse the languages. They are all reasonably orthogonal. 

42754 In particular, a parser generator that accepts the full range of LR(1) grammars need not generate 

42755 a table any more complex than one that accepts SLR(l) (a relatively weak class of LR grammars) 

42756 for a grammar that happens to be SLR(l). Such an implementation need not recognize the case, 

42757 either; table compression can yield the SLR(l) table (or one even smaller than that) without 
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recognizing that the grammar is SLR(l). The speed of an LR(1) parser for any class is dependent 
more upon the table representation and compression (or the code generation if a direct parser is 
generated) than upon the class of grammar that the table generator handles. 

The speed of the parser generator is somewhat dependent upon the class of grammar it handles. 
However, the original Knuth Article algorithms for constructing LR parsers was judged by its 
author to be impractically slow at that time. Although full LR is more complex than LALR(l), as 
computer speeds and algorithms improve, the difference (in terms of acceptable wall-clock 
execution time) is becoming less significant. 

Potential authors are cautioned that the referenced DeRemer, Frank, and Pennello Article 
previously cited identifies a bug (an over-simplification of the computation of LALR(l) 
lookahead sets) in some of the LALR(l) algorithm statements that preceded it to publication. 
They should take the time to seek out that paper, as well as current relevant work, particularly 
Aho's. 

The -b option was added to provide a portable method for permitting yacc to work on multiple 
separate parsers in the same directory. If a directory contains more than one yacc grammar, and 
both grammars are constructed at the same time (by, for example, a parallel make program), 
conflict results. While the solution is not historical practice, it corrects a known deficiency in 
historical implementations. Corresponding changes were made to all sections that referenced 
the file names y.tab.c (now "the code file"), y.tab.h (now "the header file"), and y.output (now 
"the description file"). 

The grammar for yacc input is based on System V documentation. The textual description shows 
there that the ' ;' is required at the end of the rule. The grammar and the implementation do not 
require this. (The use of C_IDENTIFIER causes a reduce to occur in the right place.) 

Also, in that implementation, the constructs such as %token can be terminated by a semicolon, 
but this is not permitted by the grammar. The keywords such as %token can also appear in 
uppercase, which is again not discussed. In most places where '%' is used, ' \' can be 
substituted, and there are alternate spellings for some of the symbols (for example, %LEFT can 
be "%<" or even "\<"). 

Historically, <tag> can contain any characters except ' >', including white space, in the 
implementation. However, since the tag must reference a ISO C standard union member, in 
practice conforming implementations need to support only the set of characters for ISO C 
standard identifiers in this context. 

Some historical implementations are known to accept actions that are terminated by a period. 
Historical implementations often allow ' $' in names. A conforming implementation does not 
need to support either of these behaviors. 

Deciding when to use %prec illustrates the difficulty in specifying the behavior of yacc. There 
may be situations in which the grammar is not, strictly speaking, in error, and yet yacc cannot 
interpret it unambiguously. The resolution of ambiguities in the grammar can in many instances 
be resolved by providing additional information, such as using %type or %union declarations. It 
is often easier and it usually yields a smaller parser to take this alternative when it is 
appropriate. 

The size and execution time of a program produced without the runtime debugging code is 
usually smaller and slightly faster in historical implementations. 

Statistics messages from several historical implementations include the following types of 
information: 
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42803 

42804 

42805 

42806 

42807 

42808 
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42820 

42821 
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42824 

42825 

42826 

42827 

42828 

42829 

42830 

42831 

42832 

42833 

42834 

42835 

42836 

42837 

42838 

42839 

42840 

42841 

42842 

42843 


n/ 512 terminals, n /300 non-terminals 

n /600 grammar rules, n/1 500 states 

n shift/reduce, n reduce/reduce conflicts reported 

n /350 working sets used 

Memory: states, etc. n/15 000, parser n /15 000 

n /600 distinct lookahead sets 

n extra closures 

n shift entries, n exceptions 

n goto entries 

n entries saved by goto default 

Optimizer space used: input n/15 000, output n/15 000 

n table entries, n zero 

Maximum spread: n, Maximum offset: n 

The report of internal tables in the description file is left implementation-dependent because all 
aspects of these limits are also implementation-dependent. Some implementations may use 
dynamic allocation techniques and have no specific limit values to report. 

The format of the y.output file is not given because specification of the format was not seen to 
enhance application portability. The listing is primarily intended to help human users 
understand and debug the parser; use of y.output by a portable application script would be 
unusual. Furthermore, implementations have not produced consistent output and no popular 
format was apparent. The format selected by the implementation should be human-readable, in 
addition to the requirement that it be a text file. 

Standard error reports are not specifically described because they are seldom of use to portable 
applications and there was no reason to restrict implementations. 

Some implementations recognize " = {" as equivalent to ' {' because it appears in historical 
documentation. This construction was recognized and documented as obsolete as long ago as 
1978, in the referenced Yacc: Yet Another Compiler-Compiler. This volume of IEEE Std. 1003.1-200x 
chose to leave it as obsolete and omit it. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

c89, lex 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

Aligned with the ISO/IEC 9945-2:1993 standard. 

Issue 5 

FUTURE DIRECTIONS section added. 

Issue 6 

Minor changes have been added to align with the IEEE P1003.2b draft standard. 

The normative text is reworded to avoid use of the term "must” for application requirements. 
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42844 NAME 

42845 zcat — expand and concatenate data 

42846 SYNOPSIS 

42847 xsi zcat [file. . . ] 

42848 

42849 DESCRIPTION 

42850 The zcat utility shall write to standard output the uncompressed form of files that have been 

42851 compressed using the compress utility. It is the equivalent of uncompress -c. Input files are not 

42852 affected. 

42853 OPTIONS 

42854 None. 


42855 OPERANDS 

42856 The following operand shall be supported: 

42857 file The path name of a file previously processed by the compress utility. If file already 

42858 has the .Z suffix specified, it is used as submitted. Otherwise, the .Z suffix is 

42859 appended to the file name prior to processing. 

42860 STDIN 

42861 The standard input shall be used only if no file operands are specified, or if a file operand is ' . 

42862 INPUT FILES 

42863 Input files shall be compressed files that are in the format produced by the compress utility. 


42864 ENVIRONMENT VARIABLES 

42865 The following environment variables shall affect the execution of zcat: 


42866 

42867 

42868 

42869 

42870 


LANG Provide a default value for the internationalization variables that are unset or null. 

If LANG is unset or null, the corresponding value from the implementation- 
dependent default locale shall be used. If any of the internationalization variables 
contains an invalid setting, the utility shall behave as if none of the variables had 
been defined. 


42871 LC_ALL If set to a non-empty string value, override the values of all the other 

42872 internationalization variables. 


42873 

42874 

42875 


LCJGTYPE Determine the locale for the interpretation of sequences of bytes of text data as 
characters (for example, single-byte as opposed to multi-byte characters in 
arguments). 


42876 

42877 

42878 


LCJAESSAGES 

Determine the locale that should be used to affect the format and contents of 
diagnostic messages written to standard error. 


42879 


NLSPATH Determine the location of message catalogs for the processing of LC_MESSAGES. 


42880 ASYNCHRONOUS EVENTS 

42881 Default. 


42882 STDOUT 

42883 The compressed files given as input shall be written on standard output in their uncompressed 

42884 form. 
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42885 STDERR 

42886 Used only for diagnostic messages. 

42887 OUTPUT FILES 

42888 None. 

42889 EXTENDED DESCRIPTION 

42890 None. 

42891 EXIT STATUS 

42892 The following exit values shall be returned: 

42893 0 Successful completion. 

42894 >0 An error occurred. 

42895 CONSEQUENCES OF ERRORS 

42896 Default. 

42897 APPLICATION USAGE 

42898 None. 

42899 EXAMPLES 

42900 None. 

42901 RATIONALE 

42902 None. 

42903 FUTURE DIRECTIONS 

42904 None. 

42905 SEE ALSO 

42906 compress, uncompress 

42907 CHANGE HISTORY 

42908 First released in Issue 4. 
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42911 Notes to Reviewers 

42912 This section with side shading will not appear in the final copy. - Ed. 

42913 This chapter needs a complete overhaul. Volunteers are wanted to tackle this task. 

42914 This chapter contains information to satisfy the recommendations of the TSG-1 Final Report 

42915 Annex A: 

42916 Section 5.1 describes perceived user requirements. 

42917 • Section 5.2 on page 1129 indicates how the facilities of this volume of IEEE Std. 1003.1-200x 

42918 satisfy those requirements. 

42919 • Section 5.3 on page 1132 offers guidance to writers of profiles on how the configurable 

42920 options, limits, and optional behavior of this volume of IEEE Std. 1003.1-200x should be cited 

42921 in profiles. 


42922 5.1 User Requirements 

42923 This section describes the user requirements that were perceived by the developers of this 

42924 volume of IEEE Std. 1003.1-200x. The primary source for these requirements was an analysis of 

42925 historical practice in widespread use, as typified by the base documents listed Chapter 1 on page 

42926 1. 

42927 The universe of users applicable to this volume of IEEE Std. 1003.1-200x is a superset of those 

42928 addressed by the System Interfaces volume of IEEE Std. 1003.1-200x: users requiring open 

42929 systems solutions for source-code portability of applications involving multi-programming and 

42930 process management (creating processes, signaling, and so on); access to files and directories in a 

42931 hierarchy of file systems (opening, reading, writing, deleting files, and so on); access to 

42932 asynchronous communications ports and other special devices; access to information about 

42933 other users of the system. The users of the System Interfaces volume of IEEE Std. 1003.1-200x are 

42934 limited to those employing applications written in high-level languages, such as C, Ada, or 

42935 FORTRAN. 

42936 The following additional users are identified for this volume of IEEE Std. 1003.1-200x: 

42937 • Users who desire portable applications that do not necessarily require the characteristics of 

42938 high-level languages (for example, the speed of execution of compiled languages or the 

42939 relative security of source code intellectual property inherent in the compilation process) 

42940 • Users who desire portable applications that can be developed quickly and can be modified 

42941 readily without the use of compilers and other system components that may be unavailable 

42942 on small systems or those without special application development capabilities 

42943 • Users who interact with a system to achieve general-purpose time-sharing capabilities 

42944 common to most business or government offices or academic environments: editing, filing, 

42945 inter-user communications, printing, and so on 

42946 • Users who develop applications for POSIX-conformant systems 

42947 An acknowledged restriction on applicable users is that they are limited to the group of 

42948 individuals who are familiar with the style of interaction characteristic of historically-derived 
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42950 

42951 

42952 

42953 

42954 

42955 

42956 

42957 

42958 
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42960 
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42976 

42977 

42978 

42979 
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42981 


systems based on one of the UNIX operating systems (as opposed to other historical systems 
with different models, such as MS/DOS, Macintosh, VMS, MVS, and so on). Typical users would 
include program developers, engineers, or general-purpose time-sharing users. 

The following subsections list the perceived requirements for this universe of users, in addition 
to those identified by the System Interfaces volume of IEEE Std. 1003.1-200x. 

5.1.1 Command Language 

Users should be able to define procedures that combine simple tools and/or applications into 
higher-level components that perform to the specific needs of the user. The user should be able 
to store, recall, use, and modify these procedures. These procedures should employ a powerful 
command language that is used for recurring tasks in portable applications (scripts) in the same 
way that it is used interactively to accomplish one-time tasks. The language and the utilities that 
it uses must be consistent between systems to reduce errors and retraining. 

5.1.2 Interactive Facilities 

Use the system to accomplish individual tasks at an interactive terminal. The interface should be 
consistent, intuitive, and offer usability enhancements to increase the productivity of terminal 
users, reduce errors, and minimize retraining costs. Online documentation or usage assistance 
should be available. 

5.1.3 Accomplish Multiple Tasks Simultaneously 

Access applications and interactive facilities from a single terminal without requiring serial 
execution: switch between multiple interactive tasks; schedule one-time or periodic background 
work; display the status of all work in progress or scheduled; influence the priority scheduling of 
work, when authorized. 

5.1.4 Complex Data Manipulation 

Manipulate data in files in complex ways: sort, merge, compare, translate, edit, format, pattern 
match, select subsets (strings, columns, fields, rows, and so on). These facilities should be 
available to both portable applications and interactive users. 

5.1.5 File Hierarchy Manipulation 

Create, delete, move/rename, copy, backup/archive, and display files and directories. These 
facilities should be available to both portable applications and interactive users. 

5.1.6 Locale Configuration 

Customize applications and interactive sessions for the cultural and language conventions of the 
user. Employ a wide variety of standard character encodings. These facilities should be available 
to both portable applications and interactive users. 


1128 


Technical Standard (2000) (Draft February 29, 2000) 



Portability Considerations (Informative) 


User Requirements 


42982 5.1.7 

Inter-User Communication 

42983 

42984 

Send messages or transfer files to other users on the same system or other systems on a network. 
These facilities should be available to both portable applications and interactive users. 

42985 5.1.8 

System Environment 

42986 

42987 

42988 

42989 

Display information about the status of the system (activities of users and their interactive and 
background work, file system utilization, system time, configuration, and presence of optional 
facilities) and the environment of the user (terminal characteristics, and so on). Inform the 
system operator/administrator of problems. Control access to user files and other resources. 

42990 5.1.9 

Printing 

42991 

42992 

42993 

42994 

Output files on a variety of output device classes, accessing devices on local or network- 
connected systems. Control (or influence) the formatting, priority scheduling, and output 
distribution of work. These facilities should be available to both portable applications and 
interactive users. 

42995 5.1.10 

Software Development 

42996 

42997 

Develop (create and manage source files, compile/interpret, debug) portable open systems 
applications and package them for distribution to, and updating of, other systems. 

42998 5.2 

Portability Capabilities 

42999 

43000 

43001 

43002 

This section describes the significant portability capabilities of this volume of 
IEEE Std. 1003.1-200x and indicates how the user requirements listed in Section 5.1 on page 1127 
are addressed. The capabilities are listed in the same format as the preceding user requirements; 
they are summarized below: 

43003 

• Command Language 

43004 

• Interactive Facilities 

43005 

• Accomplish Multiple Tasks Simultaneously 

43006 

• Complex Data Manipulation 

43007 

• File Hierarchy Manipulation 

43008 

• Locale Configuration 

43009 

• Inter-user Communication 

43010 

• System Environment 

43011 

• Printing 

43012 

• Software Development 

43013 

43014 

43015 

43016 

43017 

43018 

43019 

The shell command language, as described in Chapter 2 on page 35, is a common language 
useful in batch scripts, through an API to high-level languages (for the C-Language Binding 
option, system () and popen ()) and through an interactive terminal (see sh on page 888). The shell 
language has many of the characteristics of a high-level language, but it has been designed to be 
more suitable for user terminal entry and includes interactive debugging facilities. Through the 
use of pipelining, many complex commands can be constructed from combinations of data 
filters and other common components. Shell scripts can be created, stored, recalled, and 
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43020 modified by the user with simple editors. 

43021 In addition to the basic shell language, the following utilities offer features that simplify and 

43022 enhance programmatic access to the utilities and provide features normally found only in high- 

43023 level languages: basename, be, command, dirname, echo, env, expr, false, printf, read, sleep, tee, test, 

43024 time *, 4 true, wait, xargs, and all of the special built-in utilities in Section 2.14 on page 96. 

43025 Unsatisfied Requirements 

43026 None. 

43027 5.2.1 Interactive Facilities 

43028 The utilities offer a common style of command line interface through conformance to the Utility I 

43029 Syntax Guidelines (see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Section I 

43030 1 2.2, Utility Syntax Guidelines) and the common utility defaults (see Section 1.11 on page 25). I 

43031 The sh utility offers an interactive command line history and editing facility. The following I 

43032 utilities in the User Portability Utilities option have been customized for interactive use: alias, ex, 

43033 fc, mailx, more, talk, vi, unalias, and write-, the man utility offers online access to system 

43034 documentation. 

43035 Unsatisfied Requirements 

43036 The command line interface to individual utilities is as intuitive and consistent as historical I 

43037 practice allows. Work underway based on graphical user interfaces (see Section 1.7 on page 10) 

43038 may be more suitable for novice or occasional users of the system. 

43039 5.2.2 Accomplish Multiple Tasks Simultaneously 

43040 The shell command language offers background processing through the asynchronous list 

43041 command form; see Section 2.9.3.1 on page 74. The nohup utility makes background processing 

43042 more robust and usable. The kill utility can terminate background jobs. When the User 

43043 Portability Utilities option and the POSIX.l Job Control option are supported, the following 

43044 utilities can support more complex background work: bg, fg, and jobs. With just the User 

43045 Portability Utilities option, the following can support periodic job scheduling, control, and 

43046 display: at, batch, crontab, nice, ps, and renice. 

43047 Unsatisfied Requirements 

43048 Terminals with multiple windows may be more suitable for some multi-tasking interactive uses 

43049 than the job control approach in this volume of IEEE Std. 1003.1-200x. See the comments on 

43050 graphical user interfaces in Section 5.2.1. The nice and renice utilities do not necessarily take 

43051 advantage of complex system scheduling algorithms that are being developed by realtime 

43052 standards efforts; additional facilities are expected in future versions of this volume of 

43053 IEEE Std. 1003.1-200x. More sophisticated job processing facilities will be introduced in a future 

43054 version, based on work in supercomputing standards efforts. 


43055 - 

43056 4. The utilities listed with an asterisk are present only on systems which support the User Portability Utilities option. There may be 

43057 further restrictions on the utilities offered with various configuration option combinations; see the individual utility descriptions. 
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43058 

43059 

43060 

43061 

43062 

43063 

43064 

43065 

43066 

43067 

43068 

43069 

43070 

43071 

43072 

43073 

43074 

43075 

43076 

43077 

43078 

43079 

43080 

43081 

43082 

43083 

43084 

43085 

43086 

43087 

43088 

43089 


5.2.3 Complex Data Manipulation 

The following utilities address user requirements in this area: asa, aivk, be, emp, comm, esplit*, cut, 
dd, diff, ed, ex*, expand*, expr, find, fold, grep, head, join, od, paste, pr, printf, sed, sort, split*, tabs*, tail, 
tr, unexpand*, uniq, uudecode*, uuencode*, and zvc. 

Unsatisfied Requirements 

Sophisticated text formatting utilities, such as troff or TeX, are not included. Standards work in 
the area of SGML may satisfy this. 

5.2.4 File Hierarchy Manipulation 

The following utilities address user requirements in this area: basename, cat, cd, chgrp, chmod, 
chown, cksum, cp, dd, df*, diff, dirname, du*,find, Is, In, mkdir, mkfifo, mv, patch*, pathchk, pax, pzvd, 
rm, rmdir, test, and touch. 

Unsatisfied Requirements 

Some graphical user interfaces offer more intuitive file manager components that allow file 
manipulation through the movement of icons for novice users. 

5.2.5 Locale Configuration 

The standard utilities are affected by the various LC_ variables to achieve locale-dependent 
operation: character classification, collation sequences, REs and shell pattern matching, 
date/time formats, numeric formatting, and monetary formatting. When the 
POSIX2_LOCALEDEF option is supported, applications can provide their own locale definition 
files. The following utilities address user requirements in this area: date, ed, ex*, find, grep, locale, 
localedef, more*, sed, sh, sort, tr, uniq, and vi*. 

Unsatisfied Requirements 

Some aspects of multi-byte character and state-encoded character encodings have not yet been 
addressed. The C-language functions, such as getopt(), are generally limited to single-byte 
characters. The effect of the LC_MESSAGES variable on message formats is only suggested at 
this time, and utilities for message catalog manipulation have not been defined. 

5.2.6 Inter-User Communication 

The following utilities address user requirements in this area: cksum, mailx*, mesg*, patch*, pax, 
talk*, uudecode*, uuencode*, zvho*, and zvrite*. 

Unsatisfied Requirements 

The historical UUCP utilities are not included. This type of requirement will be addressed as 
part of networking standards efforts. 
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43090 5.2.7 

43091 

43092 

43093 

43094 

43095 

43096 5.2.8 

43097 

43098 

43099 

43100 

43101 

43102 5.2.9 

43103 

43104 

43105 

43106 

43107 

43108 

43109 

43110 

43111 

43112 


43113 5.3 

43114 

43115 

43116 

43117 

43118 

43119 

43120 

43121 

43122 
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System Environment 

The following utilities address user requirements in this area: chgrp, chmod, choivn, df*, du*, env, 
getconf, id, logger, logname, mesgf, newgrp*, ps*, stty, tpnt*, tty, umask, uname, and who*. 

Unsatisfied Requirements 

Considerable extra control of security, privilege, and auditing facilities will be added in a future 
version, based on work underway in security standards efforts. 

Printing 

The following utilities address user requirements in this area: pr and Ip. 

Unsatisfied Requirements 

There are no features to control the formatting or scheduling of the print jobs. Such facilities will 
be added in a future version, based on work underway in system administration standards 
efforts. 

Software Development 

The following utilities address user requirements in this area: ar, asa, azvk, c89, ctags*, fort77, 
getconf, getopts, lex, localedef, make, nm*, od, patch*, pax, strings*, strip, time*, and yacc. 

The system)), popen{), pclose)), regcomp (), regexec)), regerror)), regfree)), fnmatch)), getopt)), 
glob)), globfree)), wordexp)), and wordfree () functions allow C-language programmers to access 
some of the interfaces used by the utilities, such as argument processing, REs, and pattern 
matching. 

Unsatisfied Requirements 

There are no language-specific development tools related to languages other than C and 
FORTRAN. The C tools are more complete and varied than the FORTRAN tools. There is no 
source-code control system. There is no data dictionary or other CASE-like development tools. 


Profiling Considerations 

This section offers guidance to writers of profiles on how the configurable options, limits, and 
optional behavior of this volume of IEEE Std. 1003.1-200x should be cited in profiles. Profile 
writers should consult the general guidance in POSIX.O when writing POSIX Standardized 
Profiles. 

The information in this section is an inclusive list of features that should be considered by profile 
writers. Further subsetting of this volume of IEEE Std. 1003.1-200x, including the specification of 
behavior currently described as unspecified, undefined, implementation-dependent, or with the 
verbs "may" or "need not" violates the intent of the developers of this volume of 
IEEE Std. 1003.1-200x and the guidelines of ISO/IEC TR 10000-1. 
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43123 

43124 

43125 

43126 

43127 

43128 

43129 

43130 

43131 

43132 

43133 

43134 

43135 

43136 

43137 

43138 

43139 

43140 

43141 

43142 

43143 

43144 

43145 

43146 

43147 

43148 

43149 

43150 

43151 

43152 

43153 

43154 

43155 

43156 

43157 

43158 

43159 

43160 

43161 

43162 

43163 

43164 

43165 

43166 


5.3.1 Configuration Options 

There are three broad optional configurations suggested by this volume of IEEE Std. 1003.1-200x: 
basic execution system, development system, and user portability interactive system. The 
options to support these, and other minor configuration options, are listed in the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance. Profile writers 
should consult the following list and the comments concerning user requirements addressed by 
various POSIX.2 components in Section 5.2 on page 1129. 

POSIX2_UPE 

The system supports the User Portability Utilities option. 

This option is a requirement for a user portability interactive system. It is required 
frequently except for those systems, such as embedded realtime or dedicated application 
systems, that support little or no interactive time-sharing work by users or operators. 

POSIX2_SW_DEV 

The system supports the Software Development Utilities option. 

This option is required by many systems, even those in which actual software development 
does not occur. The make utility, in particular, is required by many application software 
packages as they are installed onto the system. If POSIX2_C_DEV is supported, 
POSIX2_SW_DEV is almost a mandatory requirement because of ar and make. 

POSIX2_C_BIND 

The system supports the C-Language Bindings option. 

This option is required on some systems developing complex C applications or on any 
system installing C applications in source form that require the functions in this option. The 
system)) and popen () functions, in particular, are widely used by applications; the others are 
rather more specialized. 

POSIX2_C_DEV 

The system supports the C-Language Development Utilities option. 

This option is required by many systems, even those in which actual C-language software 
development does not occur. The c89 utility, in particular, is required by many application 
software packages as they are installed onto the system. The lex and pace utilities are used 
less frequently. 

POSIX2_FORT_DEV 

The system supports the FORTRAN Development Utilities option 

As with C, this option is needed on any system developing or installing FORTRAN 
applications in source form. 

POSIX2_FORT_RUN 

The system supports the FORTRAN Runtime Utilities option. 

This option is required for some FORTRAN applications that need the asa utility to convert 
Hollerith printing statement output. It is unknown how frequently this occurs. 

POSIX2_LOCALEDEF 

The system supports the creation of locales. 

This option is needed if applications require their own customized locale definitions to 
operate. It is presently unknown whether many applications are dependent on this. 
However, the option is virtually mandatory for systems in which internationalized 
applications are developed. 
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43167 

43168 

43169 

43170 

43171 

43172 

43173 

43174 

43175 

43176 

43177 

43178 

43179 

43180 

43181 

43182 

43183 

43184 

43185 

43186 

43187 

43188 

43189 

43190 

43191 

43192 

43193 

43194 

43195 

43196 

43197 

43198 

43199 

43200 

43201 

43202 

43203 

43204 

43205 

43206 


POSIX2_CHAR_TERM 

The system supports at least one terminal type capable of all operations described in this 
volume of IEEE Std. 1003.1-200x. 

On systems with POSIX2_UPE, this option is almost always required. It was developed 
solely to allow certain specialized vendors and user applications to bypass the requirement 
for general-purpose asynchronous terminal support. For example, an application and 
system that was suitable for block-mode terminals, such as IBM 3270s, would not need this 
option. 

5.3.2 Configurable Limits 

Very few of the limits in Section 1.9 on page 21 need to be increased for profiles. No profile can 
cite lower values. 

{POSIX2_BC_B ASE_M AX} 

{POSIX2_BC_DIM_M AX} 

{POSIX2_BC_SC ALE_M AX} 

{POSIX2_BC_STRING_MAX} 

No increase is anticipated for any of these be values, except for very specialized 
applications involving huge numbers. 

{POSIX2_COLL_WEIGHTS_MAX} 

Some natural languages with complex collation requirements require an increase from 
the default 2 to 4; no higher numbers are anticipated. 

{POSIX2_EXPR_NEST_M AX [ 

No increase is anticipated. 

{POSIX2_LINE_M AX} 

This number is much larger than most historical applications have been able to use. At 
some future time, applications may be rewritten to take advantage of even larger 
values, but this is unlikely at the present time. 

{POSIX2_RE_DUP_M AX} 

No increase is anticipated. 

|POSIX2_VERSION} 

This is actually not a limit, but a standard version stamp. Generally, a profile should 
specify this volume of IEEE Std. 1003.1-200x by a name in the normative references 
section, not this value. 

5.3.3 Optional Behavior 

In this volume of IEEE Std. 1003.1-200x, there are no instances of the terms unspecified, 
undefined, or implementation-dependent, or the verbs "may" or "need not" that the developers 
of this volume of IEEE Std. 1003.1-200x anticipate or sanction as suitable for profile or test 
method citation. All of these are merely warnings to portable applications to avoid certain areas 
that can vary from system to system, and even over time on the same system. In many cases, 
these terms are used explicitly to allow for extensions, but profiles should not anticipate and 
require such extensions; future versions of this volume of IEEE Std. 1003.1-200x may do so. 
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